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