1# AbilityBase 2 3## Overview 4 5As the basic definition module of Ability Kit, AbilityBase provides definitions and APIs for [Want](want__8h.md), which can be used to transfer information between application components. 6 7**System capability**: SystemCapability.Ability.AbilityBase 8 9**Since**: 15 10 11## Summary 12 13 14### Files 15 16| Name| Description| 17| -------- | -------- | 18| [ability_base_common.h](ability__base__common_8h.md) | Declares the error codes related to AbilityBase.<br>**File to include**: <AbilityKit/ability_base/ability_base_common.h><br>**Library**: libability_base_want.so| 19| [want.h](want__8h.md) | Declares the capabilities related to [Want](want__8h.md).<br>**File to include**: <AbilityKit/ability_base/want.h><br>**Library**: libability_base_want.so| 20 21### Enums 22 23| Name | Description | 24| ------------------------------------------------------------ | ---------------------- | 25| [AbilityBase_ErrorCode](#abilitybase_errorcode) {<br> ABILITY_BASE_ERROR_CODE_NO_ERROR = 0,<br> ABILITY_BASE_ERROR_CODE_PARAM_INVALID = 401,<br>} | Enumerates the AbilityBase error codes.| 26 27### Structs 28 29| Name | Description | 30| ------------------------------------------------------------ | ---------------------------- | 31| [AbilityBase_Element](_ability_base_element.md) {<br> char* bundleName;<br> char* moduleName;<br> char* abilityName;<br>} | Element struct.| 32| [AbilityBase_Want](#abilitybase_want) | Want struct.| 33 34### Functions 35 36| Name | Description | 37| ------------------------------------------------------------ | ---------------------------- | 38| [AbilityBase_Want](#abilitybase_want)* [OH_AbilityBase_CreateWant](#oh_abilitybase_createwant)([AbilityBase_Element](_ability_base_element.md) element) | Creates Want.| 39| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_DestroyWant](#oh_abilitybase_destroywant)([AbilityBase_Want](#abilitybase_want)* want) | Destroys Want. Want cannot be used after being destroyed. Otherwise, undefined behavior may occur.| 40| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_SetWantElement](#oh_abilitybase_setwantelement)([AbilityBase_Want](#abilitybase_want)* want, [AbilityBase_Element](_ability_base_element.md) element) | Sets the Element struct, which consists of **bundleName**, **moduleName**, and **abilityName** in Want.| 41| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_GetWantElement](#oh_abilitybase_getwantelement)([AbilityBase_Want](#abilitybase_want)* want, [AbilityBase_Element](_ability_base_element.md)* element) | Obtains the Element struct, which consists of **bundleName**, **moduleName**, and **abilityName** in Want.| 42| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_SetWantCharParam](#oh_abilitybase_setwantcharparam)([AbilityBase_Want](#abilitybase_want)* want, const char* key, const char* value) | Sets **Param** in Want. For details about **Param**, see [parameters in Want](js-apis-inner-ability-want.md).| 43| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_GetWantCharParam](#oh_abilitybase_getwantcharparam)([AbilityBase_Want](#abilitybase_want)* want, const char* key, char* value, size_t valueSize) | Obtains **Param** set by [OH_AbilityBase_SetWantCharParam](#oh_abilitybase_setwantcharparam) in Want.| 44| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_AddWantFd](#oh_abilitybase_addwantfd)([AbilityBase_Want](#abilitybase_want)* want, const char* key, int32_t fd) | Adds a Want file descriptor. The file descriptor can be obtained through [fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen).| 45| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_GetWantFd](#oh_abilitybase_getwantfd)([AbilityBase_Want](#abilitybase_want)* want, const char* key, int32_t* fd) | Obtains a Want file descriptor.| 46| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_SetWantUri](#oh_abilitybase_setwanturi)([AbilityBase_Want](#abilitybase_want)* want, const char* uri) | Sets **uri** in Want. For details about **uri**, see [uri in Want](js-apis-app-ability-want.md).| 47| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_GetWantUri](#oh_abilitybase_getwanturi)([AbilityBase_Want](#abilitybase_want)* want, char* uri, size_t uriSize) | Obtains **uri** set in Want. For details about **uri**, see [uri in Want](js-apis-app-ability-want.md).| 48| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_SetWantInt32Param](#oh_abilitybase_setwantint32param)([AbilityBase_Want](#abilitybase_want)* want, const char* key, int32_t value) | Sets a value of the int32_t type in Want.| 49| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_GetWantInt32Param](#oh_abilitybase_getwantint32param)([AbilityBase_Want](#abilitybase_want)* want, const char* key, int32_t* value) | Obtains a value of the int32_t type set in Want.| 50| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_SetWantBoolParam](#oh_abilitybase_setwantboolparam)([AbilityBase_Want](#abilitybase_want)* want, const char* key, bool value) | Sets a value of the bool type in Want.| 51| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_GetWantBoolParam](#oh_abilitybase_getwantboolparam)([AbilityBase_Want](#abilitybase_want)* want, const char* key, bool* value) | Obtains a value of the bool type set in Want.| 52| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_SetWantDoubleParam](#oh_abilitybase_setwantdoubleparam)([AbilityBase_Want](#abilitybase_want)* want, const char* key, double value) | Sets a value of the double type in Want.| 53| [AbilityBase_ErrorCode](#abilitybase_errorcode) [OH_AbilityBase_GetWantDoubleParam](#oh_abilitybase_getwantdoubleparam)([AbilityBase_Want](#abilitybase_want)* want, const char* key, double* value) | Obtains a value of the double type set in Want.| 54 55 56 57## Enum Description 58 59### AbilityBase_ErrorCode 60 61``` 62enum AbilityBase_ErrorCode 63``` 64 65**Description** 66 67Enumerates the AbilityBase error codes. 68 69**Since**: 15 70 71| Value | Description | 72| --------------------------------------------- | -------------- | 73| ABILITY_BASE_ERROR_CODE_NO_ERROR | Operation successful. | 74| ABILITY_BASE_ERROR_CODE_PARAM_INVALID | Invalid parameter. | 75 76 77## Struct Description 78 79### AbilityBase_Want 80 81``` 82AbilityBase_Want 83``` 84 85**Description** 86 87Want struct. 88 89**Since**: 15 90 91 92## Function Description 93 94 95### OH_AbilityBase_CreateWant 96 97``` 98AbilityBase_Want* OH_AbilityBase_CreateWant(AbilityBase_Element element) 99``` 100**Description** 101 102Creates Want. 103 104**Since**: 15 105 106**Parameters** 107 108| Name| Description| 109| -------- | -------- | 110| element | Element struct.| 111 112**Returns** 113 114**AbilityBase_Want**, which is a Want struct. 115 116 117### OH_AbilityBase_DestroyWant 118 119``` 120AbilityBase_ErrorCode OH_AbilityBase_DestroyWant(AbilityBase_Want* want) 121``` 122**Description** 123 124Destroys Want. Want cannot be used after being destroyed. Otherwise, undefined behavior may occur. 125 126**Since**: 15 127 128**Parameters** 129 130| Name| Description| 131| -------- | -------- | 132| want | Pointer to Want.| 133 134**Returns** 135 136**ABILITY_BASE_ERROR_CODE_NO_ERROR**: Want is destroyed. 137 138**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **element** is invalid. 139 140### OH_AbilityBase_SetWantElement 141 142``` 143AbilityBase_ErrorCode OH_AbilityBase_SetWantElement(AbilityBase_Want* want, AbilityBase_Element element) 144``` 145**Description** 146 147Sets the Element struct, which consists of **bundleName**, **moduleName**, and **abilityName** in Want. 148 149**Since**: 15 150 151**Parameters** 152 153| Name| Description| 154| -------- | -------- | 155| want | Pointer to Want.| 156| element | Element struct.| 157 158**Returns** 159 160**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The setting is successful. 161 162**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or **element** is invalid. 163 164### OH_AbilityBase_GetWantElement 165 166``` 167AbilityBase_ErrorCode OH_AbilityBase_GetWantElement(AbilityBase_Want* want, AbilityBase_Element* element) 168``` 169**Description** 170 171Obtains the Element struct, which consists of **bundleName**, **moduleName**, and **abilityName** in Want. 172 173**Since**: 15 174 175**Parameters** 176 177| Name| Description| 178| -------- | -------- | 179| want | Pointer to Want.| 180| element | Pointer to the Element struct.| 181 182**Returns** 183 184**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The element struct is obtained. 185 186**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or **element** is invalid. 187 188### OH_AbilityBase_SetWantCharParam 189 190``` 191AbilityBase_ErrorCode OH_AbilityBase_SetWantCharParam(AbilityBase_Want* want, const char* key, const char* value) 192``` 193**Description** 194 195Sets **Param** in Want. For details about **Param**, see [parameters in Want](js-apis-inner-ability-want.md). 196 197**Since**: 15 198 199**Parameters** 200 201| Name| Description| 202| -------- | -------- | 203| want | Pointer to Want.| 204| key | Pointer to a key in Want.| 205| value | Pointer to the value of the key in Want.| 206 207**Returns** 208 209**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The setting is successful. 210 211**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 212 213### OH_AbilityBase_GetWantCharParam 214 215``` 216AbilityBase_ErrorCode OH_AbilityBase_GetWantCharParam(AbilityBase_Want* want, const char* key, char* value, size_t valueSize) 217``` 218**Description** 219 220Obtains **Param** set by [OH_AbilityBase_SetWantCharParam](#oh_abilitybase_setwantcharparam) in Want. 221 222**Since**: 15 223 224**Parameters** 225 226| Name| Description| 227| -------- | -------- | 228| want | Pointer to Want.| 229| key | Pointer to a key in Want.| 230| value | Pointer to the value of the key in Want.| 231| valueSize | Length of the value string. If **valueSize** is less than the actual value length, the **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** error is reported.| 232 233**Returns** 234 235**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The param struct is obtained. 236 237**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 238 239### OH_AbilityBase_AddWantFd 240 241``` 242AbilityBase_ErrorCode OH_AbilityBase_AddWantFd(AbilityBase_Want* want, const char* key, int32_t fd) 243``` 244**Description** 245 246Adds a Want file descriptor. The file descriptor can be obtained through [fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen). 247 248**Since**: 15 249 250**Parameters** 251 252| Name| Description| 253| -------- | -------- | 254| want | Pointer to Want.| 255| key | Pointer to a key in Want.| 256| fd | File descriptor, which is obtained by calling [fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen).| 257 258**Returns** 259 260**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The Want file descriptor is added. 261 262**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 263 264### OH_AbilityBase_GetWantFd 265 266``` 267AbilityBase_ErrorCode OH_AbilityBase_GetWantFd(AbilityBase_Want* want, const char* key, int32_t* fd) 268``` 269**Description** 270 271Obtains a Want file descriptor. 272 273**Since**: 15 274 275**Parameters** 276 277| Name| Description| 278| -------- | -------- | 279| want | Pointer to Want.| 280| key | Pointer to a key in Want.| 281| fd | Pointer to the file descriptor.| 282 283**Returns** 284 285**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The Want file descriptor is obtained. 286 287**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 288 289### OH_AbilityBase_SetWantUri 290 291``` 292AbilityBase_ErrorCode OH_AbilityBase_SetWantUri(AbilityBase_Want* want, const char* uri) 293``` 294**Description** 295 296Sets **uri** in Want. For details about **uri**, see [uri in Want](js-apis-app-ability-want.md). 297 298**Since**: 17 299 300**Parameters** 301 302| Name| Description| 303| -------- | -------- | 304| want | Pointer to Want.| 305| uri | Pointer to a URI. If a URI is specified in Want, Want will match the specified URI information. For details, see [uri in Want](js-apis-app-ability-want.md).| 306 307**Returns** 308 309**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The setting is successful. 310 311**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 312 313### OH_AbilityBase_GetWantUri 314 315``` 316AbilityBase_ErrorCode OH_AbilityBase_GetWantUri(AbilityBase_Want* want, char* uri, size_t uriSize) 317``` 318**Description** 319 320Obtains **uri** set in Want. For details about **uri**, see [uri in Want](js-apis-app-ability-want.md). 321 322**Since**: 17 323 324**Parameters** 325 326| Name| Description| 327| -------- | -------- | 328| want | Pointer to Want.| 329| uri | Pointer to a URI. If a URI is specified in Want, Want will match the specified URI information. For details, see [uri in Want](js-apis-app-ability-want.md).| 330| uriSize | Length of the URI string. If **uriSize** is less than the actual URI length, the **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** error is reported.| 331 332**Returns** 333 334**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The URI string in Want is obtained. 335 336**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 337 338### OH_AbilityBase_SetWantInt32Param 339 340``` 341AbilityBase_ErrorCode OH_AbilityBase_SetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t value) 342``` 343**Description** 344 345Sets a value of the int32_t type in Want. 346 347**Since**: 17 348 349**Parameters** 350 351| Name| Description| 352| -------- | -------- | 353| want | Pointer to Want.| 354| key | Pointer to the key in Want.| 355| value | Value of the int32_t type of the key.| 356 357**Returns** 358 359**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The setting is successful. 360 361**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 362 363### OH_AbilityBase_GetWantInt32Param 364 365``` 366AbilityBase_ErrorCode OH_AbilityBase_GetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t* value) 367``` 368**Description** 369 370Obtains a value of the int32_t type set in Want. 371 372**Since**: 17 373 374**Parameters** 375 376| Name| Description| 377| -------- | -------- | 378| want | Pointer to Want.| 379| key | Pointer to the key in Want.| 380| value | Pointer to the value of the int32_t type of the key.| 381 382**Returns** 383 384**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The value of the int32_t type is obtained. 385 386**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 387 388 389### OH_AbilityBase_SetWantBoolParam 390 391``` 392AbilityBase_ErrorCode OH_AbilityBase_SetWantBoolParam(AbilityBase_Want* want, const char* key, bool value) 393``` 394**Description** 395 396Sets a value of the bool type in Want. 397 398**Since**: 17 399 400**Parameters** 401 402| Name| Description| 403| -------- | -------- | 404| want | Pointer to Want.| 405| key | Pointer to the key in Want.| 406| value | Value of the bool type of the key.| 407 408**Returns** 409 410**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The setting is successful. 411 412**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 413 414### OH_AbilityBase_GetWantBoolParam 415 416``` 417AbilityBase_ErrorCode OH_AbilityBase_GetWantBoolParam(AbilityBase_Want* want, const char* key, bool* value) 418``` 419**Description** 420 421Obtains a value of the bool type set in Want. 422 423**Since**: 17 424 425**Parameters** 426 427| Name| Description| 428| -------- | -------- | 429| want | Pointer to Want.| 430| key | Pointer to the key in Want.| 431| value | Pointer to the value of the bool type of the key.| 432 433**Returns** 434 435**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The value of the bool type is obtained. 436 437**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 438 439### OH_AbilityBase_SetWantDoubleParam 440 441``` 442AbilityBase_ErrorCode OH_AbilityBase_SetWantDoubleParam(AbilityBase_Want* want, const char* key, double value) 443``` 444**Description** 445 446Sets a value of the double type in Want. 447 448**Since**: 17 449 450**Parameters** 451 452| Name| Description| 453| -------- | -------- | 454| want | Pointer to Want.| 455| key | Pointer to the key in Want.| 456| value | Value of the double type of the key.| 457 458**Returns** 459 460**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The setting is successful. 461 462**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 463 464### OH_AbilityBase_GetWantDoubleParam 465 466``` 467AbilityBase_ErrorCode OH_AbilityBase_GetWantDoubleParam(AbilityBase_Want* want, const char* key, double* value) 468``` 469**Description** 470 471Obtains a value of the double type set in Want. 472 473**Since**: 17 474 475**Parameters** 476 477| Name| Description| 478| -------- | -------- | 479| want | Pointer to Want.| 480| key | Pointer to the key in Want.| 481| value | Pointer to the value of the double type of the key.| 482 483**Returns** 484 485**ABILITY_BASE_ERROR_CODE_NO_ERROR**: The value of the double type is successfully obtained. 486 487**ABILITY_BASE_ERROR_CODE_PARAM_INVALID**: **want** is null or invalid. 488