• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2020 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 /**
17  * @addtogroup parameter
18  * @{
19  *
20  * @brief Provides functions for obtaining system parameters.
21  *
22  * This module can obtain device information such as device type and manufacturer.\n
23  *
24  * @since 6.0
25  * @version 6.0
26  */
27 
28 /**
29  * @file parameter.h
30  *
31  * @brief Declares functions for obtaining system parameters.
32  *
33  * You can use the provided functions to obtain device information such as device type and manufacturer.\n
34  * @since 6.0
35  * @version 6.0
36  */
37 
38 #ifndef PARAMETER_API_H
39 #define PARAMETER_API_H
40 
41 #ifdef __cplusplus
42 #if __cplusplus
43 extern "C" {
44 #endif
45 #endif /* __cplusplus */
46 
47 /**
48  * @brief Obtains a system parameter matching the specified <b>key</b>.
49  *
50  * If no system parameter is found, the <b>def</b> parameter will be returned.\n
51  *
52  * @param key Indicates the key for the system parameter to query.
53  * The value can contain lowercase letters, digits, underscores (_), and dots (.).
54  * Its length cannot exceed 32 bytes (including the end-of-text character in the string).
55  * @param def Indicates the default value to return when no query result is found.
56  * This parameter is specified by the caller.
57  * @param value Indicates the data buffer that stores the query result.
58  * This parameter is applied for and released by the caller and can be used as an output parameter.
59  * @param len Indicates the length of the data in the buffer.
60  * @return Returns the number of bytes of the system parameter if the operation is successful;
61  * returns <b>-9</b> if a parameter is incorrect; returns <b>-1</b> in other scenarios.
62  * @since 6.0
63  * @version 6.0
64  */
65 int GetParameter(const char *key, const char *def, char *value, unsigned int len);
66 
67 /**
68  * @brief Sets or updates a system parameter.
69  *
70  * You can use this function to set a system parameter that matches <b>key</b> as <b>value</b>.\n
71  *
72  * @param key Indicates the key for the parameter to set or update.
73  * The value can contain lowercase letters, digits, underscores (_), and dots (.).
74  * Its length cannot exceed 32 bytes (including the end-of-text character in the string).
75  * @param value Indicates the system parameter value.
76  * Its length cannot exceed 128 bytes (including the end-of-text character in the string).
77  * @return Returns <b>0</b> if the operation is successful;
78  * returns <b>-9</b> if a parameter is incorrect; returns <b>-1</b> in other scenarios.
79  * @since 6.0
80  * @version 6.0
81  */
82 int SetParameter(const char *key, const char *value);
83 
84 /**
85  * @brief Wait for a system parameter with specified value.
86  *
87  * You can use this function to wait a system parameter that matches <b>key</b> as <b>value</b>.\n
88  *
89  * @param key Indicates the key for the parameter to wait.
90  * The value can contain lowercase letters, digits, underscores (_), and dots (.).
91  * Its length cannot exceed 96 bytes (including the end-of-text character in the string).
92  * @param value Indicates the system parameter value.
93  * Its length cannot exceed 96 bytes (including the end-of-text character in the string).
94  * value can use "*" to do arbitrary match.
95  * @param timeout Indicates the timeout value, in seconds.
96  * <=0 means wait for ever.
97  * >0 means wait for specified seconds
98  * @return Returns <b>0</b> if the operation is successful;
99  * returns <b>-10</b> if timeout; returns <b>-1</b> in other scenarios.
100  * @since 1.1
101  * @version 1.1
102  */
103 int WaitParameter(const char *key, const char *value, int timeout);
104 
105 /**
106  * @brief Watch for system parameter values.
107  *
108  * You can use this function to watch system parameter values.\n
109  *
110  * @param keyprefix Indicates the key prefix for the parameter to be watched.
111  * If keyprefix is not a full name, "A.B." for example, it means to watch for all parameter started with "A.B.".
112  * @param callback Indicates value change callback.
113  * If callback is NULL, it means to cancel the watch.
114  * @return Returns <b>0</b> if the operation is successful;
115  * returns <b>-1</b> in other scenarios.
116  * @since 1.1
117  * @version 1.1
118  */
119 typedef void (*ParameterChgPtr)(const char *key, const char *value, void *context);
120 int WatchParameter(const char *keyprefix, ParameterChgPtr callback, void *context);
121 
122 /**
123  * @brief Obtains the device type.
124  *
125  * The device type can have a maximum length of 32 characters.\n
126  *
127  * @return Returns the device type if a result is found, for example, returns <b>wifiiot</b>
128  * if the application is running on a Wi-Fi connected IoT device; returns <b>NULL</b> otherwise.
129  * @since 6.0
130  * @version 6.0 */
131 const char *GetDeviceType(void);
132 
133 /**
134  * @brief Obtains the device manufacturer.
135  *
136  * The device manufacturer can have a maximum length of 32 characters.\n
137  *
138  * @return Returns the device manufacturer if a result is found; returns <b>NULL</b> otherwise.
139  * @since 6.0
140  * @version 6.0
141  */
142 const char *GetManufacture(void);
143 
144 /**
145  * @brief Obtains the device brand.
146  *
147  * The device brand can have a maximum length of 32 characters.\n
148  *
149  * @return Returns the device brand if a result is found; returns <b>NULL</b> otherwise.
150  * @since 6.0
151  * @version 6.0
152  */
153 const char *GetBrand(void);
154 
155 /**
156  * @brief Obtains the device marketing name.
157  *
158  * The device marketing name can have a maximum length of 32 characters.\n
159  *
160  * @return Returns the device marketing name if a result is found; returns <b>NULL</b> otherwise.
161  * @since 6.0
162  * @version 6.0
163  */
164 const char *GetMarketName(void);
165 
166 /**
167  * @brief Obtains the device series name.
168  *
169  * The device series name can have a maximum length of 32 characters.\n
170  *
171  * @return Returns the device series name if a result is found; returns <b>NULL</b> otherwise.
172  * @since 6.0
173  * @version 6.0
174  */
175 const char *GetProductSeries(void);
176 
177 /**
178  * @brief Obtains the device authentication model.
179  *
180  * The device authentication model can have a maximum length of 32 characters.\n
181  *
182  * @return Returns the device authentication model if a result is found; returns <b>NULL</b> otherwise.
183  * @since 6.0
184  * @version 6.0
185  */
186 const char *GetProductModel(void);
187 
188 /**
189  * @brief Obtains the device software model.
190  *
191  * The device software model can have a maximum length of 32 characters.\n
192  *
193  * @return Returns the device software model if a result is found; returns <b>NULL</b> otherwise.
194  * @since 6.0
195  * @version 6.0 */
196 const char *GetSoftwareModel(void);
197 
198 /**
199  * @brief Obtains the device hardware model.
200  *
201  * The device hardware model can have a maximum length of 32 characters.\n
202  *
203  * @return Returns the device hardware model if a result is found; returns <b>NULL</b> otherwise.
204  * @since 6.0
205  * @version 6.0
206  */
207 const char *GetHardwareModel(void);
208 
209 /**
210  * @brief Obtains the device hardware profile.
211  *
212  * The device hardware profile is a string in JSON format and has a maximum length of 1000 characters.\n
213  *
214  * @return Returns the device hardware profile if a result is found; returns <b>NULL</b> otherwise.
215  * The JSON field in the device hardware profile is defined as follows:
216  * Description | key
217  * -----------|-----------
218  * Audio playback | aout
219  * Display | display
220  * Camera | camera
221  * 2D acceleration capability | DMA_2D
222  * Random-access memory | RAM
223  * Read-only memory | ROM
224  * Graphics processing unit | GPU
225  * Neural-network processing unit | NPU
226  * Radio | radio
227  * Bluetooth | bluetooth
228  * Wi-Fi | WIFI
229  * USB | usbhost
230  * @since 6.0
231  * @version 6.0
232  */
233 const char *GetHardwareProfile(void);
234 
235 /**
236  * @brief Obtains the device serial number (SN).
237  *
238  * The device SN can have a maximum length of 64 characters.\n
239  *
240  * @return Returns the device SN if a result is found; returns <b>NULL</b> otherwise.
241  * @since 6.0
242  * @version 6.0
243  */
244 const char *GetSerial(void);
245 
246 /**
247  * @brief Obtains the operating system (OS) name.
248  *
249  * The device OS name can have a maximum length of 32 characters.\n
250  *
251  * @return Returns the device OS name if a result is found; returns <b>NULL</b> otherwise.
252  * @since 6.0
253  * @version 6.0
254  */
255 const char *GetOSFullName(void);
256 
257 /**
258  * @brief Obtains the software version visible to users.
259  *
260  * The software version visible to users can have a maximum length of 64 characters.\n
261  *
262  * @return Returns the software version visible to users if a result is found; returns <b>NULL</b> otherwise.
263  * @since 6.0
264  * @version 6.0
265  */
266 const char *GetDisplayVersion(void);
267 
268 /**
269  * @brief Obtains the bootloader version of this device.
270  *
271  * The bootloader version can have a maximum length of 64 characters.\n
272  *
273  * @return Returns the bootloader version if a result is found; returns <b>NULL</b> otherwise.
274  * @since 6.0
275  * @version 6.0
276  */
277 const char *GetBootloaderVersion(void);
278 
279 /**
280  * @brief Obtains the security patch tag.
281  *
282  * @return Returns the security patch tag if a result is found; returns <b>NULL</b> otherwise.
283  * @since 6.0
284  * @version 6.0
285  */
286 const char *GetSecurityPatchTag(void);
287 
288 /**
289  * @brief Obtains the list of application binary interfaces (ABIs) supported on this device.
290  *
291  * The interfaces in the ABI list are separated by commas (,).
292  * This function is available only for an OS with an ecosystem accommodating native applications.\n
293  *
294  * @return Returns the ABI list if a result is found; returns <b>NULL</b> otherwise.
295  * @since 6.0
296  * @version 6.0
297  */
298 const char *GetAbiList(void);
299 
300 /**
301  * @brief Obtains the SDK API version that matches the current system software.
302  *
303  * In general, the SDK API version is an integer. This function is only available for an OS with an ecosystem.\n
304  *
305  * @return Returns the SDK API version if a result is found; returns <b>NULL</b> otherwise.
306  * @since 6.0
307  * @version 6.0
308  */
309 int GetSdkApiVersion(void);
310 
311 /**
312  * @brief Obtains the first SDK API version of the system software.
313  *
314  * In general, the first SDK API version is an integer. This function is only available for an OS with an ecosystem.\n
315  *
316  * @return Returns the first SDK API version if a result is found; returns <b>NULL</b> otherwise.
317  * @since 6.0
318  * @version 6.0
319  */
320 int GetFirstApiVersion(void);
321 
322 /**
323  * @brief Obtains the incremental version.
324  *
325  * The incremental version can be used as the unique software version when the device model is the same.\n
326  *
327  * @return Returns the incremental version if a result is found; returns <b>NULL</b> otherwise.
328  * @since 6.0
329  * @version 6.0
330  */
331 const char *GetIncrementalVersion(void);
332 
333 /**
334  * @brief Obtains the version ID.
335  *
336  * The version ID can have a maximum length of 127 characters. It is the unique identifier of a device.\n
337  *
338  * @return Returns the version ID if a result is found; returns <b>NULL</b> otherwise.
339  * @since 6.0
340  * @version 6.0
341  */
342 const char *GetVersionId(void);
343 
344 /**
345  * @brief Obtains the build type.
346  *
347  * Different build types with the same baseline codes will be returned,
348  * for example, <b>debug/release</b> and <b>log/nolog</b>.
349  * Multiple build types can be separated by semicolons (;).\n
350  *
351  * @return Returns the build type if a result is found; returns <b>NULL</b> otherwise.
352  * @since 6.0
353  * @version 6.0
354  */
355 const char *GetBuildType(void);
356 
357 /**
358  * @brief Obtains the build account user name.
359  *
360  * The build account user name can have a maximum length of 32 characters.\n
361  *
362  * @return Returns the build account user name if a result is found; returns <b>NULL</b> otherwise.
363  * @since 6.0
364  * @version 6.0
365  */
366 const char *GetBuildUser(void);
367 
368 /**
369  * @brief Obtains the build host name.
370  *
371  * The build host name can have a maximum length of 32 characters.\n
372  *
373  * @return Returns the build host name if a result is found; returns <b>NULL</b> otherwise.
374  * @since 6.0
375  * @version 6.0
376  */
377 const char *GetBuildHost(void);
378 
379 /**
380  * @brief Obtains the version build time.
381  *
382  * The version build time is represented by the number of milliseconds elapsed since 1970-01-01 00:00:00 GMT.\n
383  *
384  * @return Returns the version build time if a result is found; returns <b>NULL</b> otherwise.
385  * @since 6.0
386  * @version 6.0
387  */
388 const char *GetBuildTime(void);
389 
390 /**
391  * @brief Obtains the buildroot hash value of this version.
392  *
393  * The buildroot hash value is represented by the root hash value in the software version hash tree.\n
394  *
395  * @return Returns the buildroot hash value if a result is found; returns <b>NULL</b> otherwise.
396  * @since 6.0
397  * @version 6.0
398  */
399 const char *GetBuildRootHash(void);
400 
401 /**
402  * @brief Obtains the OS release type.
403  *
404  * The OS release category can be Release, Beta, Canary.
405  * The specific release type may be Release, Beta1, or others alike.\n
406  *
407  * @return Returns the OS Release Type.
408  * @since 6.0
409  * @version 6.0
410  */
411 const char *GetOsReleaseType(void);
412 
413 /**
414  * @brief Obtains the device udid.
415  *
416  * The OS release category can be Release, Beta, Canary.
417  * The specific release type may be Release, Beta1, or others alike.\n
418  *
419  * @return Return 0 if a result is found; return fail label otherwise.
420  * @since 7.0
421  * @version 7.0
422  */
423 int GetDevUdid(char *udid, int size);
424 
425 #ifdef __cplusplus
426 #if __cplusplus
427 }
428 #endif
429 #endif /* __cplusplus */
430 
431 #endif // PARAMETER_API_H
432 /** @} */
433