• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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#abilitybase_element) {<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#abilitybase_element) 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#abilitybase_element) 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#abilitybase_element)* 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
114Returns **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
136Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if Want is destroyed.
137
138Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **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
160Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the setting is successful.
161
162Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is set to a null pointer 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
184Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the element struct is obtained.
185
186Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is set to a null pointer 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
209Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the setting is successful.
210
211Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer 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
235Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the param struct is obtained.
236
237Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer 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
260Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the Want file descriptor is added.
261
262Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer 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
285Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the Want file descriptor is obtained.
286
287Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
288
289### OH_AbilityBase_SetWantUri
290
291```
292AbilityBase_ErrorCode OH_AbilityBase_SetWantUri(AbilityBase_Want* want, const char* uri)
293```
294
295**Description**
296
297Sets **uri** in Want. For details about **uri**, see [uri in Want](js-apis-app-ability-want.md).
298
299**Valid since**: 18
300
301**Parameters**
302
303| Name| Description|
304| -------- | -------- |
305| want | Pointer to Want.|
306| 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).|
307
308**Returns**
309
310Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the setting is successful.
311
312Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
313
314### OH_AbilityBase_GetWantUri
315
316```
317AbilityBase_ErrorCode OH_AbilityBase_GetWantUri(AbilityBase_Want* want, char* uri, size_t uriSize)
318```
319
320**Description**
321
322Obtains **uri** set in Want. For details about **uri**, see [uri in Want](js-apis-app-ability-want.md).
323
324**Valid since**: 18
325
326**Parameters**
327
328| Name| Description|
329| -------- | -------- |
330| want | Pointer to Want.|
331| 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).|
332| 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.|
333
334**Returns**
335
336Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the URI string in Want is successfully obtained.
337
338Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
339
340### OH_AbilityBase_SetWantInt32Param
341
342```
343AbilityBase_ErrorCode OH_AbilityBase_SetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t value)
344```
345
346**Description**
347
348Sets a value of the int32_t type in Want.
349
350**Valid since**: 18
351
352**Parameters**
353
354| Name| Description|
355| -------- | -------- |
356| want | Pointer to Want.|
357| key | Pointer to the key in Want.|
358| value | Value of the int32_t type of the key.|
359
360**Returns**
361
362Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the setting is successful.
363
364Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
365
366### OH_AbilityBase_GetWantInt32Param
367
368```
369AbilityBase_ErrorCode OH_AbilityBase_GetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t* value)
370```
371
372**Description**
373
374Obtains a value of the int32_t type set in Want.
375
376**Valid since**: 18
377
378**Parameters**
379
380| Name| Description|
381| -------- | -------- |
382| want | Pointer to Want.|
383| key | Pointer to the key in Want.|
384| value | Pointer to the value of the int32_t type of the key.|
385
386**Returns**
387
388Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the value of the int32_t type is successfully obtained.
389
390Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
391
392
393### OH_AbilityBase_SetWantBoolParam
394
395```
396AbilityBase_ErrorCode OH_AbilityBase_SetWantBoolParam(AbilityBase_Want* want, const char* key, bool value)
397```
398
399**Description**
400
401Sets a value of the bool type in Want.
402
403**Valid since**: 18
404
405**Parameters**
406
407| Name| Description|
408| -------- | -------- |
409| want | Pointer to Want.|
410| key | Pointer to the key in Want.|
411| value | Value of the bool type of the key.|
412
413**Returns**
414
415Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the setting is successful.
416
417Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
418
419### OH_AbilityBase_GetWantBoolParam
420
421```
422AbilityBase_ErrorCode OH_AbilityBase_GetWantBoolParam(AbilityBase_Want* want, const char* key, bool* value)
423```
424
425**Description**
426
427Obtains a value of the bool type set in Want.
428
429**Valid since**: 18
430
431**Parameters**
432
433| Name| Description|
434| -------- | -------- |
435| want | Pointer to Want.|
436| key | Pointer to the key in Want.|
437| value | Pointer to the value of the bool type of the key.|
438
439**Returns**
440
441Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the value of the bool type is successfully obtained.
442
443Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
444
445### OH_AbilityBase_SetWantDoubleParam
446
447```
448AbilityBase_ErrorCode OH_AbilityBase_SetWantDoubleParam(AbilityBase_Want* want, const char* key, double value)
449```
450
451**Description**
452
453Sets a value of the double type in Want.
454
455**Valid since**: 18
456
457**Parameters**
458
459| Name| Description|
460| -------- | -------- |
461| want | Pointer to Want.|
462| key | Pointer to the key in Want.|
463| value | Value of the double type of the key.|
464
465**Returns**
466
467Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the setting is successful.
468
469Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
470
471### OH_AbilityBase_GetWantDoubleParam
472
473```
474AbilityBase_ErrorCode OH_AbilityBase_GetWantDoubleParam(AbilityBase_Want* want, const char* key, double* value)
475```
476
477**Description**
478
479Obtains a value of the double type set in Want.
480
481**Valid since**: 18
482
483**Parameters**
484
485| Name| Description|
486| -------- | -------- |
487| want | Pointer to Want.|
488| key | Pointer to the key in Want.|
489| value | Pointer to the value of the double type of the key.|
490
491**Returns**
492
493Returns **ABILITY_BASE_ERROR_CODE_NO_ERROR** if the value of the double type is successfully obtained.
494
495Returns **ABILITY_BASE_ERROR_CODE_PARAM_INVALID** if **want** is a null pointer or invalid.
496