1# want.h 2 3## 概述 4 5Want是对象间信息传递的载体，可以用于应用组件间的信息传递。 Want的使用场景之一是作为startAbility的参数，其包含了指定的启动目标，以及启动时需携带的相关数据，如bundleName和abilityName字段分别指明目标Ability所在应用的Bundle名称以及对应包内的Ability名称。当Ability A需要启动Ability B并传入一些数据时，可使用Want作为载体将这些数据传递给Ability B。 6 7**引用文件：** <AbilityKit/ability_base/want.h> 8 9**库：** libability_base_want.so 10 11**系统能力：** SystemCapability.Ability.AbilityBase 12 13**起始版本：** 15 14 15**相关模块：** [AbilityBase](capi-abilitybase.md) 16 17## 汇总 18 19### 结构体 20 21| 名称 | typedef关键字 | 描述 | 22| -- | -- | -- | 23| [AbilityBase_Element](capi-abilitybase-element.md) | AbilityBase_Element | 声明Want中Element结构体。 | 24| [AbilityBase_Want](capi-abilitybase-want.md) | AbilityBase_Want | 声明Want数据结构。 | 25 26### 函数 27 28| 名称 | 描述 | 29| -- | -- | 30| [AbilityBase_Want* OH_AbilityBase_CreateWant(AbilityBase_Element element)](#oh_abilitybase_createwant) | 创建Want。 | 31| [AbilityBase_ErrorCode OH_AbilityBase_DestroyWant(AbilityBase_Want* want)](#oh_abilitybase_destroywant) | 销毁Want。销毁后的Want不可使用，否则会导致未定义行为。 | 32| [AbilityBase_ErrorCode OH_AbilityBase_SetWantElement(AbilityBase_Want* want, AbilityBase_Element element)](#oh_abilitybase_setwantelement) | 设置Want中由bundleName、moduleName与abilityName组成的Element结构体。 | 33| [AbilityBase_ErrorCode OH_AbilityBase_GetWantElement(AbilityBase_Want* want, AbilityBase_Element* element)](#oh_abilitybase_getwantelement) | 获取Want中由bundleName、moduleName与abilityName组成的Element结构体。 | 34| [AbilityBase_ErrorCode OH_AbilityBase_SetWantCharParam(AbilityBase_Want* want, const char* key, const char* value)](#oh_abilitybase_setwantcharparam) | 设置Want Param参数。 | 35| [AbilityBase_ErrorCode OH_AbilityBase_GetWantCharParam(AbilityBase_Want* want, const char* key,char* value, size_t valueSize)](#oh_abilitybase_getwantcharparam) | 获取Want Param参数。 | 36| [AbilityBase_ErrorCode OH_AbilityBase_AddWantFd(AbilityBase_Want* want, const char* key, int32_t fd)](#oh_abilitybase_addwantfd) | 添加Want文件描述符。 | 37| [AbilityBase_ErrorCode OH_AbilityBase_GetWantFd(AbilityBase_Want* want, const char* key, int32_t* fd)](#oh_abilitybase_getwantfd) | 获取Want文件描述符。 | 38| [AbilityBase_ErrorCode OH_AbilityBase_SetWantUri(AbilityBase_Want* want, const char* uri)](#oh_abilitybase_setwanturi) | 设置Want中URI字符串。 | 39| [AbilityBase_ErrorCode OH_AbilityBase_GetWantUri(AbilityBase_Want* want, char* uri, size_t uriSize)](#oh_abilitybase_getwanturi) | 获取Want中URI字符串。URI可参考[Want中uri描述](js-apis-app-ability-want.md)。 | 40| [AbilityBase_ErrorCode OH_AbilityBase_SetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t value)](#oh_abilitybase_setwantint32param) | 设置Want中int32_t类型的值。 | 41| [AbilityBase_ErrorCode OH_AbilityBase_GetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t* value)](#oh_abilitybase_getwantint32param) | 获取Want中int32_t类型的值。 | 42| [AbilityBase_ErrorCode OH_AbilityBase_SetWantBoolParam(AbilityBase_Want* want, const char* key, bool value)](#oh_abilitybase_setwantboolparam) | 设置Want中bool类型的值。 | 43| [AbilityBase_ErrorCode OH_AbilityBase_GetWantBoolParam(AbilityBase_Want* want, const char* key, bool* value)](#oh_abilitybase_getwantboolparam) | 获取Want中bool类型的值。 | 44| [AbilityBase_ErrorCode OH_AbilityBase_SetWantDoubleParam(AbilityBase_Want* want, const char* key, double value)](#oh_abilitybase_setwantdoubleparam) | 设置Want中double类型的值。 | 45| [AbilityBase_ErrorCode OH_AbilityBase_GetWantDoubleParam(AbilityBase_Want* want, const char* key, double* value)](#oh_abilitybase_getwantdoubleparam) | 获取Want中double类型的值。 | 46 47## 函数说明 48 49### OH_AbilityBase_CreateWant() 50 51``` 52AbilityBase_Want* OH_AbilityBase_CreateWant(AbilityBase_Element element) 53``` 54 55**描述** 56 57创建Want。 58 59**起始版本：** 15 60 61 62**参数：** 63 64| 参数项 | 描述 | 65| -- | -- | 66| [AbilityBase_Element](capi-abilitybase-element.md) element | Element数据结构。 | 67 68**返回：** 69 70| 类型 | 说明 | 71| -- | -- | 72| [AbilityBase_Want](capi-abilitybase-want.md)* | 返回want数据结构。 | 73 74### OH_AbilityBase_DestroyWant() 75 76``` 77AbilityBase_ErrorCode OH_AbilityBase_DestroyWant(AbilityBase_Want* want) 78``` 79 80**描述** 81 82销毁Want。销毁后的Want不可使用，否则会导致未定义行为。 83 84**起始版本：** 15 85 86**参数：** 87 88| 参数项 | 描述 | 89| -- | -- | 90| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 91 92**返回：** 93 94| 类型 | 说明 | 95| -- | -- | 96| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 销毁want成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - element参数无效。 | 97 98### OH_AbilityBase_SetWantElement() 99 100``` 101AbilityBase_ErrorCode OH_AbilityBase_SetWantElement(AbilityBase_Want* want, AbilityBase_Element element) 102``` 103 104**描述** 105 106设置Want中由bundleName、moduleName与abilityName组成的Element结构体。 107 108**起始版本：** 15 109 110 111**参数：** 112 113| 参数项 | 描述 | 114| -- | -- | 115| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 116| [AbilityBase_Element](capi-abilitybase-element.md) element | Element结构体。 | 117 118**返回：** 119 120| 类型 | 说明 | 121| -- | -- | 122| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 设置element成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空，element参数无效。 | 123 124### OH_AbilityBase_GetWantElement() 125 126``` 127AbilityBase_ErrorCode OH_AbilityBase_GetWantElement(AbilityBase_Want* want, AbilityBase_Element* element) 128``` 129 130**描述** 131 132获取Want中由bundleName、moduleName与abilityName组成的Element结构体。 133 134**起始版本：** 15 135 136 137**参数：** 138 139| 参数项 | 描述 | 140| -- | -- | 141| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 142| [AbilityBase_Element](capi-abilitybase-element.md)* element | Element结构体。 | 143 144**返回：** 145 146| 类型 | 说明 | 147| -- | -- | 148| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 获取element成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空，element参数无效。 | 149 150### OH_AbilityBase_SetWantCharParam() 151 152``` 153AbilityBase_ErrorCode OH_AbilityBase_SetWantCharParam(AbilityBase_Want* want, const char* key, const char* value) 154``` 155 156**描述** 157 158设置Want Param参数，Param可参考[Want中的parameters参数](js-apis-inner-ability-want.md)。 159 160**起始版本：** 15 161 162**参数：** 163 164| 参数项 | 描述 | 165| -- | -- | 166| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 167| const char* key | Want中字符串参数索引。 | 168| const char* value | Want中字符串。 | 169 170**返回：** 171 172| 类型 | 说明 | 173| -- | -- | 174| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 设置param成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 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**描述** 183 184获取[OH_AbilityBase_SetWantCharParam](#oh_abilitybase_setwantcharparam)方法设置的Want Param参数。 185 186**起始版本：** 15 187 188 189**参数：** 190 191| 参数项 | 描述 | 192| -- | -- | 193| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 194| const char* key | Want中字符串参数索引。 | 195| char* value | Want中字符串。 | 196| size_t valueSize | value字符串长度。如果valueSize小于实际需要获取的value长度，则会报[ABILITY_BASE_ERROR_CODE_PARAM_INVALID](capi-ability-base-common-h.md#abilitybase_errorcode)错误。 | 197 198**返回：** 199 200| 类型 | 说明 | 201| -- | -- | 202| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 获取param成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 203 204### OH_AbilityBase_AddWantFd() 205 206``` 207AbilityBase_ErrorCode OH_AbilityBase_AddWantFd(AbilityBase_Want* want, const char* key, int32_t fd) 208``` 209 210**描述** 211 212添加Want文件描述符，文件描述符可通过[fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen)获取。 213 214**起始版本：** 15 215 216**参数：** 217 218| 参数项 | 描述 | 219| -- | -- | 220| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 221| const char* key | Want中字符串参数索引。 | 222| int32_t fd | 文件描述符，可通过[fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen)获取。 | 223 224**返回：** 225 226| 类型 | 说明 | 227| -- | -- | 228| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 添加want文件描述符成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 229 230### OH_AbilityBase_GetWantFd() 231 232``` 233AbilityBase_ErrorCode OH_AbilityBase_GetWantFd(AbilityBase_Want* want, const char* key, int32_t* fd) 234``` 235 236**描述** 237 238获取Want文件描述符。 239 240**起始版本：** 15 241 242**参数：** 243 244| 参数项 | 描述 | 245| -- | -- | 246| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 247| const char* key | Want中字符串参数索引。 | 248| int32_t* fd | 文件描述符。 | 249 250**返回：** 251 252| 类型 | 说明 | 253| -- | -- | 254| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 获取want文件描述符成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 255 256### OH_AbilityBase_SetWantUri() 257 258``` 259AbilityBase_ErrorCode OH_AbilityBase_SetWantUri(AbilityBase_Want* want, const char* uri) 260``` 261 262**描述** 263 264设置Want中URI字符串，URI可参考[Want中URI描述](js-apis-app-ability-want.md)。 265 266**起始版本：** 17 267 268**参数：** 269 270| 参数项 | 描述 | 271| -- | -- | 272| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 273| const char* uri | 表示URI。如果在Want中指定了URI，则Want将匹配指定的URI信息。URI可参考[Want中URI描述](js-apis-app-ability-want.md)。 | 274 275**返回：** 276 277| 类型 | 说明 | 278| -- | -- | 279| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 设置want中uri字符串成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 280 281### OH_AbilityBase_GetWantUri() 282 283``` 284AbilityBase_ErrorCode OH_AbilityBase_GetWantUri(AbilityBase_Want* want, char* uri, size_t uriSize) 285``` 286 287**描述** 288 289获取Want中URI字符串。URI可参考[Want中URI描述](js-apis-app-ability-want.md)。 290 291**起始版本：** 17 292 293**参数：** 294 295| 参数项 | 描述 | 296| -- | -- | 297| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 298| char* uri | 表示URI。如果在Want中指定了URI，则Want将匹配指定的URI信息。URI可参考[Want中URI描述](js-apis-app-ability-want.md)。 | 299| size_t uriSize | URI字符串长度。如果uriSize小于实际需要获取的URI长度，则会报[ABILITY_BASE_ERROR_CODE_PARAM_INVALID](capi-ability-base-common-h.md#abilitybase_errorcode)错误。 | 300 301**返回：** 302 303| 类型 | 说明 | 304| -- | -- | 305| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 获取want中URI字符串成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 306 307### OH_AbilityBase_SetWantInt32Param() 308 309``` 310AbilityBase_ErrorCode OH_AbilityBase_SetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t value) 311``` 312 313**描述** 314 315设置Want中int32_t类型的值。 316 317**起始版本：** 17 318 319 320**参数：** 321 322| 参数项 | 描述 | 323| -- | -- | 324| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 325| const char* key | Want中int32_t类型值的参数索引。 | 326| int32_t value | Want中int32_t类型的值。 | 327 328**返回：** 329 330| 类型 | 说明 | 331| -- | -- | 332| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 设置want中int32_t类型的值成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 333 334### OH_AbilityBase_GetWantInt32Param() 335 336``` 337AbilityBase_ErrorCode OH_AbilityBase_GetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t* value) 338``` 339 340**描述** 341 342获取Want中int32_t类型的值。 343 344**起始版本：** 17 345 346**参数：** 347 348| 参数项 | 描述 | 349| -- | -- | 350| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 351| const char* key | Want中int32_t类型值的参数索引。 | 352| int32_t* value | Want中int32_t类型的值。 | 353 354**返回：** 355 356| 类型 | 说明 | 357| -- | -- | 358| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 获取want中int32_t类型的值成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 359 360### OH_AbilityBase_SetWantBoolParam() 361 362``` 363AbilityBase_ErrorCode OH_AbilityBase_SetWantBoolParam(AbilityBase_Want* want, const char* key, bool value) 364``` 365 366**描述** 367 368设置Want中bool类型的值。 369 370**起始版本：** 17 371 372**参数：** 373 374| 参数项 | 描述 | 375| -- | -- | 376| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 377| const char* key | Want中bool类型值的参数索引。 | 378| bool value | Want中bool类型的值。 | 379 380**返回：** 381 382| 类型 | 说明 | 383| -- | -- | 384| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 设置want中bool类型的值成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 385 386### OH_AbilityBase_GetWantBoolParam() 387 388``` 389AbilityBase_ErrorCode OH_AbilityBase_GetWantBoolParam(AbilityBase_Want* want, const char* key, bool* value) 390``` 391 392**描述** 393 394获取Want中bool类型的值。 395 396**起始版本：** 17 397 398**参数：** 399 400| 参数项 | 描述 | 401| -- | -- | 402| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 403| const char* key | Want中bool类型值的参数索引。 | 404| bool* value | Want中bool类型的值。 | 405 406**返回：** 407 408| 类型 | 说明 | 409| -- | -- | 410| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 获取want中bool类型的值成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 411 412### OH_AbilityBase_SetWantDoubleParam() 413 414``` 415AbilityBase_ErrorCode OH_AbilityBase_SetWantDoubleParam(AbilityBase_Want* want, const char* key, double value) 416``` 417 418**描述** 419 420设置Want中double类型的值。 421 422**起始版本：** 17 423 424**参数：** 425 426| 参数项 | 描述 | 427| -- | -- | 428| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 429| const char* key | Want中double类型值的参数索引。 | 430| double value | Want中double类型的值。 | 431 432**返回：** 433 434| 类型 | 说明 | 435| -- | -- | 436| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 设置want中double类型的值成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 437 438### OH_AbilityBase_GetWantDoubleParam() 439 440``` 441AbilityBase_ErrorCode OH_AbilityBase_GetWantDoubleParam(AbilityBase_Want* want, const char* key, double* value) 442``` 443 444**描述** 445 446获取Want中double类型的值。 447 448**起始版本：** 17 449 450**参数：** 451 452| 参数项 | 描述 | 453| -- | -- | 454| [AbilityBase_Want](capi-abilitybase-want.md)* want | Want指针。 | 455| const char* key | Want中double类型值的参数索引。 | 456| double* value | Want中double类型的值。 | 457 458**返回：** 459 460| 类型 | 说明 | 461| -- | -- | 462| [AbilityBase_ErrorCode](capi-ability-base-common-h.md#abilitybase_errorcode) | 返回执行结果。<br>ABILITY_BASE_ERROR_CODE_NO_ERROR - 获取want中double类型的值成功。<br>ABILITY_BASE_ERROR_CODE_PARAM_INVALID - want为空或非法入参。 | 463