want.h

Overview

Want 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.

File to include: <AbilityKit/ability_base/want.h>

Library: libability_base_want.so

System capability: SystemCapability.Ability.AbilityBase

Since: 15

Related module: AbilityBase

Summary

Structs

Name	typedef Keyword	Description
AbilityBase_Element	AbilityBase_Element	Declares the Element struct in Want.
AbilityBase_Want	AbilityBase_Want	Declares the struct of Want data.

Functions

Name	Description
AbilityBase_Want* OH_AbilityBase_CreateWant(AbilityBase_Element element)	Creates Want.
AbilityBase_ErrorCode OH_AbilityBase_DestroyWant(AbilityBase_Want* want)	Destroys Want. Want cannot be used after being destroyed. Otherwise, undefined behavior may occur.
AbilityBase_ErrorCode OH_AbilityBase_SetWantElement(AbilityBase_Want* want, AbilityBase_Element element)	Sets the Element struct, which consists of bundleName, moduleName, and abilityName in Want.
AbilityBase_ErrorCode OH_AbilityBase_GetWantElement(AbilityBase_Want* want, AbilityBase_Element* element)	Obtains the Element struct, which consists of bundleName, moduleName, and abilityName in Want.
AbilityBase_ErrorCode OH_AbilityBase_SetWantCharParam(AbilityBase_Want* want, const char* key, const char* value)	Sets Param in Want.
AbilityBase_ErrorCode OH_AbilityBase_GetWantCharParam(AbilityBase_Want* want, const char* key,char* value, size_t valueSize)	Obtains Param in Want.
AbilityBase_ErrorCode OH_AbilityBase_AddWantFd(AbilityBase_Want* want, const char* key, int32_t fd)	Adds a Want file descriptor.
AbilityBase_ErrorCode OH_AbilityBase_GetWantFd(AbilityBase_Want* want, const char* key, int32_t* fd)	Obtains a Want file descriptor.
AbilityBase_ErrorCode OH_AbilityBase_SetWantUri(AbilityBase_Want* want, const char* uri)	Sets uri in Want.
AbilityBase_ErrorCode OH_AbilityBase_GetWantUri(AbilityBase_Want* want, char* uri, size_t uriSize)	Obtains uri set in Want. For details about the URI, see uri in Want.
AbilityBase_ErrorCode OH_AbilityBase_SetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t value)	Sets a value of the int32_t type in Want.
AbilityBase_ErrorCode OH_AbilityBase_GetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t* value)	Obtains a value of the int32_t type set in Want.
AbilityBase_ErrorCode OH_AbilityBase_SetWantBoolParam(AbilityBase_Want* want, const char* key, bool value)	Sets a value of the bool type in Want.
AbilityBase_ErrorCode OH_AbilityBase_GetWantBoolParam(AbilityBase_Want* want, const char* key, bool* value)	Obtains a value of the bool type set in Want.
AbilityBase_ErrorCode OH_AbilityBase_SetWantDoubleParam(AbilityBase_Want* want, const char* key, double value)	Sets a value of the double type in Want.
AbilityBase_ErrorCode OH_AbilityBase_GetWantDoubleParam(AbilityBase_Want* want, const char* key, double* value)	Obtains a value of the double type set in Want.

Function Description

OH_AbilityBase_CreateWant()

AbilityBase_Want* OH_AbilityBase_CreateWant(AbilityBase_Element element)

Description

Creates Want.

Since: 15

Parameters

Name	Description
AbilityBase_Element element	Element struct.

Returns

Type	Description
AbilityBase_Want*	Pointer to Want.

OH_AbilityBase_DestroyWant()

AbilityBase_ErrorCode OH_AbilityBase_DestroyWant(AbilityBase_Want* want)

Description

Destroys Want. Want cannot be used after being destroyed. Otherwise, undefined behavior may occur.

Since: 15

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: Want is destroyed. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: element is invalid.

OH_AbilityBase_SetWantElement()

AbilityBase_ErrorCode OH_AbilityBase_SetWantElement(AbilityBase_Want* want, AbilityBase_Element element)

Description

Sets the Element struct, which consists of bundleName, moduleName, and abilityName in Want.

Since: 15

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
AbilityBase_Element element	Element struct.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The setting is successful. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or element is invalid.

OH_AbilityBase_GetWantElement()

AbilityBase_ErrorCode OH_AbilityBase_GetWantElement(AbilityBase_Want* want, AbilityBase_Element* element)

Description

Obtains the Element struct, which consists of bundleName, moduleName, and abilityName in Want.

Since: 15

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
AbilityBase_Element* element	Pointer to the Element struct.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The element struct is obtained. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or element is invalid.

OH_AbilityBase_SetWantCharParam()

AbilityBase_ErrorCode OH_AbilityBase_SetWantCharParam(AbilityBase_Want* want, const char* key, const char* value)

Description

Sets Param in Want. For details about Param, see parameters in Want.

Since: 15

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
const char* value	Pointer to the value of the key in Want.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The setting is successful. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_GetWantCharParam()

AbilityBase_ErrorCode OH_AbilityBase_GetWantCharParam(AbilityBase_Want* want, const char* key,char* value, size_t valueSize)

Description

Obtains Param set by OH_AbilityBase_SetWantCharParam in Want.

Since: 15

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
char* value	Pointer to the value of the key in Want.
size_t 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.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The param struct is obtained. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_AddWantFd()

AbilityBase_ErrorCode OH_AbilityBase_AddWantFd(AbilityBase_Want* want, const char* key, int32_t fd)

Description

Adds a Want file descriptor. The file descriptor can be obtained through fs.open.

Since: 15

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
int32_t fd	File descriptor, which is obtained by calling fs.open.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The Want file descriptor is added. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_GetWantFd()

AbilityBase_ErrorCode OH_AbilityBase_GetWantFd(AbilityBase_Want* want, const char* key, int32_t* fd)

Description

Obtains a Want file descriptor.

Since: 15

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
int32_t* fd	Pointer to the file descriptor.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The Want file descriptor is obtained. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_SetWantUri()

AbilityBase_ErrorCode OH_AbilityBase_SetWantUri(AbilityBase_Want* want, const char* uri)

Description

Sets uri in Want. For details about the URI, see uri in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
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.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The setting is successful. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_GetWantUri()

AbilityBase_ErrorCode OH_AbilityBase_GetWantUri(AbilityBase_Want* want, char* uri, size_t uriSize)

Description

Obtains uri set in Want. For details about the URI, see uri in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
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.
size_t 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.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The URI string in Want is obtained. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_SetWantInt32Param()

AbilityBase_ErrorCode OH_AbilityBase_SetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t value)

Description

Sets a value of the int32_t type in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
int32_t value	Value of the int32_t type of the key.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The setting is successful. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_GetWantInt32Param()

AbilityBase_ErrorCode OH_AbilityBase_GetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t* value)

Description

Obtains a value of the int32_t type set in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
int32_t* value	Pointer to the value of the int32_t type of the key.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The value of the int32_t type is obtained. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_SetWantBoolParam()

AbilityBase_ErrorCode OH_AbilityBase_SetWantBoolParam(AbilityBase_Want* want, const char* key, bool value)

Description

Sets a value of the bool type in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
bool value	Value of the bool type of the key.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The setting is successful. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_GetWantBoolParam()

AbilityBase_ErrorCode OH_AbilityBase_GetWantBoolParam(AbilityBase_Want* want, const char* key, bool* value)

Description

Obtains a value of the bool type set in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
bool* value	Pointer to the value of the bool type of the key.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The value of the bool type is obtained. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_SetWantDoubleParam()

AbilityBase_ErrorCode OH_AbilityBase_SetWantDoubleParam(AbilityBase_Want* want, const char* key, double value)

Description

Sets a value of the double type in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
double value	Value of the double type of the key.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The setting is successful. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.

OH_AbilityBase_GetWantDoubleParam()

AbilityBase_ErrorCode OH_AbilityBase_GetWantDoubleParam(AbilityBase_Want* want, const char* key, double* value)

Description

Obtains a value of the double type set in Want.

Since: 17

Parameters

Name	Description
AbilityBase_Want* want	Pointer to Want.
const char* key	Pointer to a key in Want.
double* value	Pointer to the value of the double type of the key.

Returns

Type	Description
AbilityBase_ErrorCode	One of the following execution results: ABILITY_BASE_ERROR_CODE_NO_ERROR: The value of the double type is obtained. ABILITY_BASE_ERROR_CODE_PARAM_INVALID: want is null or invalid.