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