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