AbilityKit

Abilities are classified into Abilities and Particle Abilities. Feature Abilities support the Page template, and Particle Abilities support the template. An ability using the Page template is called a Page ability for short and that using the Service template is called a ability.

Since:

1.0

Version:

1.0

Summary

Files

Data Structures

Data Structure Name	Description
OHOS::Ability	Declares ability-related functions, including ability lifecycle callbacks and functions for connecting to or disconnecting from Particle Abilities.
	Provides callbacks to be invoked when a remote Service ability is connected or disconnected.
	Provides functions for starting and stopping an ability.
OHOS::AbilityEventHandler	Declares functions for performing operations during inter-thread communication, including running and quitting the event loop of the current thread and posting tasks to an asynchronous thread.
	Declares functions for registering the class names of Ability and with the ability management framework.
OHOS::AbilitySlice	Provides ability slice-related functions, including ability slice lifecycle callbacks and functions for connecting to or disconnecting from ability slices.
	Defines the abstract description of an operation, including information about the ability and the extra data to carry.

Macros

Macro Name and Value	Description
(className)	Registers the class name of an Ability child class.
REGISTER_AS(className)	Registers the class name of an AbilitySlice child class.

Enumerations

Enumeration Name	Description
{ ERR_OK = 0, , MEMORY_MALLOC_ERROR, , IPC_REQUEST_ERROR, , COMMAND_ERROR = 0x7fff }	Declares error codes returned by ability management functions.
{ STATE_UNINITIALIZED, , STATE_INACTIVE, , STATE_BACKGROUND }	Enumerates all lifecycle states that an ability will go through over the course of its lifetime.

Functions

Function Name	Description
OHOS::Ability::OnStart (const &want)	virtual void Called when this ability is started. You must override this function if you want to perform some initialization operations during ability startup.
OHOS::Ability::OnInactive ()	virtual void Called when this ability enters the STATE_INACTIVE state.
(const Want &want)	virtual void Called when this ability enters the STATE_ACTIVE state.
()	virtual void Called when this ability enters the STATE_BACKGROUND state.
OHOS::Ability::OnStop ()	virtual void Called when this ability enters the STATE_STOP state.
(const Want &want)	virtual const SvcIdentity Called when this ability is connected for the first time.
OHOS::Ability::OnDisconnect (const &want)	virtual void Called when all abilities connected to this Service ability are disconnected.
(const std::string &entry)	void Sets the main route for this ability.
(RootView rootView)	void Sets the UI layout for this ability. You can call GetWindowRootView() to create a layout and add controls.
(uint32_t funcId, IpcIo request, IpcIo reply)	virtual void Handles a message sent by the client to this Service ability.
(const std::string &extra)	virtual void Prints ability information to the console.
OHOS::AbilityContext::StartAbility (const &want)	int Starts an Ability based on the specified information.
OHOS::AbilityContext::StopAbility (const &want)	int Stops an Ability based on the specified information.
OHOS::AbilityContext::TerminateAbility ()	int Destroys this .
OHOS::AbilityContext::ConnectAbility (const &want, const IAbilityConnection &conn, void data)	int Connects to a ability based on the specified Want information.
(const IAbilityConnection &conn)	int Disconnects from a ability.
GetBundleName ()	const char Obtains the bundle name of the application to which this ability belongs.
()	const char Obtains the source code path of this ability.
GetDataPath ()	const char Obtains the data path of this ability.
OHOS::AbilityEventHandler::Run ()	void Starts running the event loop of the current thread.
(const Task &task)	void Posts a task to an asynchronous thread.
OHOS::AbilityEventHandler::PostQuit ()	void Quits the event loop of the current thread.
OHOS::AbilityEventHandler::GetCurrentHandler ()	static Obtains the event handler of the current thread.
StartAbility (const want)	int Starts an ability based on the specified Want information.
(const Want want)	int Stops an ability based on the specified information.
ConnectAbility (const want, const IAbilityConnection conn, void data)	int Connects to a ability based on the specified Want information.
(const IAbilityConnection conn)	int Disconnects from a ability.
OHOS::AbilitySlice::OnStart (const &want)	virtual void Called when this ability slice is started. You must override this function if you want to perform some initialization operations during ability slice startup.
OHOS::AbilitySlice::OnInactive ()	virtual void Called when this ability slice enters the STATE_INACTIVE state.
(const Want &want)	virtual void Called when this ability slice enters the STATE_ACTIVE state.
()	virtual void Called when this ability slice enters the STATE_BACKGROUND state.
OHOS::AbilitySlice::OnStop ()	virtual void Called when this ability slice enters the STATE_STOP state.
(AbilitySlice &abilitySlice, const &want)	Presents another ability slice, which can be an ability slice that is not started or an existing ability slice in the host ability.
OHOS::AbilitySlice::Terminate ()	void Destroys this ability slice.
(RootView rootView)	void Sets the UI layout for the host ability of this ability slice.
(Want want)	void Clears the memory of a specified object.
SetWantElement ( want, ElementName element)	bool Sets the element variable for a specified object.
SetWantData ( want, const void data, uint16_t dataLength)	bool Sets data to carry in a specified Want object for starting a particular ability.
(Want want, SvcIdentity sid)	bool Sets the sid member variable for a specified object.
WantToUri ( want)	const char Converts a specified Want object into a character string.
(const char uri)	Want Converts a specified character string into a object.

Details

Macro Definition Documentation

REGISTER_AA


 AbilityLoader::GetInstance().RegisterAbility(#className, []()->Ability* { \
 return new className; \
 }); \
 }

Description:

Registers the class name of an Ability child class.

After implementing your own Ability class, you should call this function so that the ability management framework can create Ability instances when loading your Ability class.

Parameters:

Name	Description
className	Indicates the Ability class name to register.

REGISTER_AS

#define REGISTER_AS( className)

Values: __attribute__((constructor)) void RegisterAS##className() { \
 AbilityLoader::GetInstance().RegisterAbilitySlice(#className, []()->AbilitySlice* { \
 return new className; \
 }); \
 }

Description:

Registers the class name of an AbilitySlice child class.

After implementing your own AbilitySlice class, you should call this function so that the ability management framework can create AbilitySlice instances when loading your AbilitySlice class.

Parameters:

Name	Description
className	Indicates the AbilitySlice class name to register.

Enumeration Type Documentation

anonymous enum

Description:

Declares error codes returned by ability management functions.

Enumerator	Description
ERR_OK	The function is successfully called.
PARAM_NULL_ERROR	The parameter is null.
MEMORY_MALLOC_ERROR	Memory allocation error.
DUMP_ABILITIES_ERROR	An error occurred during the execution of the Dump function.
IPC_REQUEST_ERROR	IPC request error.
SERIALIZE_ERROR	Serialization error.
COMMAND_ERROR	Command error.

State

Description:

Enumerates all lifecycle states that an ability will go through over the course of its lifetime.

Enumerator	Description
STATE_UNINITIALIZED	Uninitialized state: An ability is in this state when it has not been initialized after being created.
STATE_INITIAL	Initial state: An ability is in this state after it is initialized or stopped.
STATE_INACTIVE	Inactive state: An ability is in this state when it is switched to the foreground but is not interactive.
STATE_ACTIVE	Active state: An ability is in this state when it is switched to the foreground and is interactive.
STATE_BACKGROUND	Background state: An ability is in this state after it returns to the background.

Function Documentation

ClearWant()

void ClearWant ([Want]($api-api-SmartVision-Devices-Want.md) * want)

Description:

Clears the memory of a specified Want object.

After calling functions such as , you should call this function to clear the memory.

Parameters:

Name	Description
want	Indicates the pointer to the object whose memory is to be released.

ConnectAbility() [1/2]

int OHOS::AbilityContext::ConnectAbility (const [Want]($api-api-SmartVision-Devices-Want.md) & want, const [IAbilityConnection]($api-api-SmartVision-Devices-IAbilityConnection.md) & conn, void * data )

Description:

Connects to a Service ability based on the specified information.

After the Service ability is connected, the Manager Service invokes a particular callback and returns the ID of the ability. The client can use this ID to communicate with the connected Service ability.

Parameters:

Name	Description
want	Indicates the pointer to the Want structure containing information about the ability to connect.
conn	Indicates the callback to be invoked when the connection is successful.
data	Indicates the pointer to the data to be passed to the callback.

Returns:

Returns 0 if this function is successfully called; returns another value otherwise.

ConnectAbility() [2/2]

int ConnectAbility (const [Want]($api-api-SmartVision-Devices-Want.md) * want, const [IAbilityConnection]($api-api-SmartVision-Devices-IAbilityConnection.md) * conn, void * data )

Description:

Connects to a Service ability based on the specified information.

After the Service ability is connected, the AMS invokes the particular callback and returns the ID of the ability. The client can use this ID to communicate with the connected Service ability.

Parameters:

Name	Description
want	Indicates the pointer to the Want structure containing information about the ability to connect.
conn	Indicates the callback object when the Service ability is connected.
data	Indicates the pointer to the data to be passed to the callback.

Returns:

Returns 0 if this function is successfully called; returns another value otherwise.

DisconnectAbility() [1/2]

int OHOS::AbilityContext::DisconnectAbility (const [IAbilityConnection]($api-api-SmartVision-Devices-IAbilityConnection.md) & conn)

Description:

Disconnects from a ability.

Parameters:

Returns:

Returns 0 if this function is successfully called; returns another value otherwise.

int DisconnectAbility (const [IAbilityConnection]($api-api-SmartVision-Devices-IAbilityConnection.md) * conn)

Description:

Disconnects from a ability.

Parameters:

Name	Description
conn	Indicates the callback object when the ability is connected.

Returns:

Returns 0 if this function is successfully called; returns another value otherwise.

Dump()

virtual void OHOS::Ability::Dump (const std::string & extra)

Description:

Prints ability information to the console.

You can override this function to obtain or print extra parameters.

Parameters:

Name	Description
extra	Indicates the extra parameter to be obtained or printed to the console.

GetBundleName()

const char* GetBundleName ()

Description:

Obtains the bundle name of the application to which this ability belongs.

Returns:

Returns the pointer to the bundle name if the operation is successful; returns a null pointer otherwise.

GetCurrentHandler()

static [AbilityEventHandler]($api-api-SmartVision-Devices-OHOS-AbilityEventHandler.md)* OHOS::AbilityEventHandler::GetCurrentHandler ()

Description:

Obtains the event handler of the current thread.

Returns:

Returns the pointer to the object of the current thread.

GetDataPath()

const char* GetDataPath ()

Description:

Obtains the data path of this ability.

Returns:

Returns the pointer to the data path of this ability.

GetSrcPath()

Description:

Obtains the source code path of this ability.

Returns:

Returns the pointer to the source code path of this ability.

MsgHandle()

virtual void OHOS::Ability::MsgHandle (uint32_t funcId, IpcIo * request, IpcIo * reply )

Description:

Handles a message sent by the client to this Service ability.

Parameters:

Name	Description
funcId	Indicates the type of the message sent by the client.
request	Indicates the pointer to the serialized request parameters sent by the client.
reply	Indicates the pointer to the serialized result returned to the client.

OnActive() [1/2]

virtual void OHOS::AbilitySlice::OnActive (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

Called when this ability slice enters the STATE_ACTIVE state.

The ability slice in the STATE_ACTIVE state is visible and has focus. You can override this function to implement your own processing logic.

Parameters:

Name	Description
want	Indicates the structure containing activation information about the ability slice.

OnActive() [2/2]

virtual void OHOS::Ability::OnActive (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

Called when this ability enters the STATE_ACTIVE state.

The ability in the STATE_ACTIVE state is visible and has focus. You can override this function to implement your own processing logic.

Parameters:

Name	Description
want	Indicates the structure containing activation information about the ability.

OnBackground() [1/2]

virtual void OHOS::AbilitySlice::OnBackground ()

Description:

Called when this ability slice enters the STATE_BACKGROUND state.

The ability slice in the STATE_BACKGROUND state is invisible. You can override this function to implement your own processing logic.

OnBackground() [2/2]

virtual void OHOS::Ability::OnBackground ()

Description:

Called when this ability enters the STATE_BACKGROUND state.

The ability in the STATE_BACKGROUND state is invisible. You can override this function to implement your own processing logic.

OnConnect()

virtual const SvcIdentity* OHOS::Ability::OnConnect (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

Called when this Service ability is connected for the first time.

You can override this function to implement your own processing logic.

Parameters:

Name	Description
want	Indicates the Want structure containing connection information about the ability.

Returns:

Returns a pointer to the sid of the connected Service ability.

OnDisconnect()

virtual void OHOS::Ability::OnDisconnect (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

You can override this function to implement your own processing logic.

Parameters:

Name	Description
want	Indicates the Want structure containing disconnection information about the ability.

OnInactive() [1/2]

virtual void OHOS::AbilitySlice::OnInactive ()

Description:

Called when this ability slice enters the STATE_INACTIVE state.

STATE_INACTIVE is an instantaneous state. The ability slice in this state may be visible but does not have focus. You can override this function to implement your own processing logic.

OnInactive() [2/2]

Description:

Called when this ability enters the STATE_INACTIVE state.

STATE_INACTIVE is an instantaneous state. The ability in this state may be visible but does not have focus. You can override this function to implement your own processing logic.

OnStart() [1/2]

virtual void OHOS::AbilitySlice::OnStart (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

Called when this ability slice is started. You must override this function if you want to perform some initialization operations during ability slice startup.

This function can be called only once in the entire lifecycle of an ability slice. You can override this function to implement your own processing logic.

Parameters:

Name	Description
want	Indicates the structure containing startup information about the ability slice.

OnStart() [2/2]

virtual void OHOS::Ability::OnStart (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

Called when this ability is started. You must override this function if you want to perform some initialization operations during ability startup.

This function can be called only once in the entire lifecycle of an ability.

Parameters:

Name	Description
want	Indicates the structure containing startup information about the ability.

OnStop() [1/2]

virtual void OHOS::AbilitySlice::OnStop ()

Description:

Called when this ability slice enters the STATE_STOP state.

The ability slice in the STATE_STOP state is being destroyed. You can override this function to implement your own processing logic.

OnStop() [2/2]

virtual void OHOS::Ability::OnStop ()

Description:

Called when this ability enters the STATE_STOP state.

The ability in the STATE_STOP is being destroyed. You can override this function to implement your own processing logic.

void OHOS::AbilityEventHandler::PostTask (const Task & task)

Description:

Posts a task to an asynchronous thread.

Parameters:

Name	Description
task	Indicates the task to post.

Present()

Description:

Presents another ability slice, which can be an ability slice that is not started or an existing ability slice in the host ability.

Parameters:

Name	Description
abilitySlice	Indicates the target ability slice. This parameter cannot be null.
want	Indicates the Want structure containing startup information about the target ability slice.

Attention:

This function can be called only when both of the following conditions are met:

The host ability is in the STATE_ACTIVE state.
The target ability slice is not started or destroyed.

SetMainRoute()

void OHOS::Ability::SetMainRoute (const std::string & entry)

Description:

Sets the main route for this ability.

The main route, also called main entry, refers to the default to present for this ability. This function should be called only on Feature Abilities. If this function is not called in the function for a Feature , the Feature will fail to start.

Parameters:

SetUIContent() [1/2]

void OHOS::AbilitySlice::SetUIContent ([RootView]($api-api-SmartVision-Devices-OHOS-RootView.md) * rootView)

Description:

Sets the UI layout for the host ability of this ability slice.

You can call GetWindowRootView() to create a layout and add controls.

Parameters:

Name	Description
rootView	Indicates the pointer to the custom layout view you have created.

SetUIContent() [2/2]

void OHOS::Ability::SetUIContent ([RootView]($api-api-SmartVision-Devices-OHOS-RootView.md) * rootView)

Description:

Sets the UI layout for this ability. You can call GetWindowRootView() to create a layout and add controls.

Parameters:

Name	Description
rootView	Indicates the pointer to the custom layout view you have created.

SetWantData()

bool SetWantData ([Want]($api-api-SmartVision-Devices-Want.md) * want, const void * data, uint16_t dataLength )

Description:

Sets data to carry in a specified object for starting a particular ability.

Parameters:

Name	Description
want	Indicates the pointer to the object to set.
data	Indicates the pointer to the data to set.
dataLength	Indicates the data length to set. The length must be the same as that of the data specified in data.

Returns:

Returns true if the setting is successful; returns false otherwise.

SetWantElement()

bool SetWantElement ([Want]($api-api-SmartVision-Devices-Want.md) * want, [ElementName]($api-api-SmartVision-Devices-ElementName.md) element )

Description:

Sets the element variable for a specified Want object.

To start a specified ability, you should call this function to set the required for starting the ability.

Parameters:

Name	Description
want	Indicates the pointer to the object to set.
element	Indicates the ElementName containing information required for starting the ability.

Returns:

Returns true if the setting is successful; returns false otherwise.

SetWantSvcIdentity()

bool SetWantSvcIdentity ([Want]($api-api-SmartVision-Devices-Want.md) * want, SvcIdentity sid )

Description:

Sets the sid member variable for a specified object.

When starting an ability, you should call this function to set an SvcIdentity object if a callback needs to be invoked after the ability is started successfully.

Parameters:

Name	Description
want	Indicates the pointer to the object to set.
sid	Indicates the SvcIdentity object to set.

Returns:

Returns true if the setting is successful; returns false otherwise.

StartAbility() [1/2]

int OHOS::AbilityContext::StartAbility (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

Starts an Ability based on the specified information.

Parameters:

Name	Description
want	Indicates the pointer to the structure containing information about the ability to start.

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

StartAbility() [2/2]

int StartAbility (const [Want]($api-api-SmartVision-Devices-Want.md) * want)

Description:

Starts an ability based on the specified Want information.

Parameters:

Name	Description
want	Indicates the pointer to the Want structure containing information about the ability to start.

Returns:

Returns 0 if this function is successfully called; returns another value otherwise.

StopAbility() [1/2]

int OHOS::AbilityContext::StopAbility (const [Want]($api-api-SmartVision-Devices-Want.md) & want)

Description:

Stops an based on the specified Want information.

This function takes effect only on abilities.

Parameters:

Name	Description
want	Indicates the pointer to the structure containing information about the ability to stop.

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

StopAbility() [2/2]

int StopAbility (const [Want]($api-api-SmartVision-Devices-Want.md) * want)

Description:

Stops an ability based on the specified Want information.

This function takes effect only on abilities.

Parameters:

Name	Description
want	Indicates the pointer to the structure containing information about the ability to stop.

Returns:

Returns 0 if this function is successfully called; returns another value otherwise.

Terminate()

void OHOS::AbilitySlice::Terminate ()

Description:

Destroys this ability slice.

This ability slice can call this function to destroy itself. If the ability slice to destroy is the only running one in the host ability, the host ability will also be destroyed. Otherwise, the host ability will not be affected.

TerminateAbility()

int OHOS::AbilityContext::TerminateAbility ()

Description:

Destroys this Ability.

This function can be called only by this ability.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

WantParseUri()

[Want]($api-api-SmartVision-Devices-Want.md)* WantParseUri (const char * uri)

Description:

Converts a specified character string into a object.

Parameters:

Name	Description
uri	Indicates the pointer to the character string to convert.

Returns:

Returns the pointer to the converted object if the operation is successful; returns nullptr otherwise.

WantToUri()

Description:

Converts a specified Want object into a character string.

Parameters:

Name	Description
want	Indicates the Want object to convert.

Returns:

Returns the converted character string if the operation is successful; returns nullptr otherwise.

Variable Documentation

OnAbilityConnectDone

Description:

Called when a client is connected to a ability.

This callback is invoked to receive the connection result after a client is connected to a Service ability.

Parameters:

OnAbilityDisconnectDone

void(* IAbilityConnection::OnAbilityDisconnectDone) ([ElementName]($api-api-SmartVision-Devices-ElementName.md) *elementName, int resultCode, void *data)

Description:

Called after all connections to a Service ability are disconnected.

This callback is invoked to receive the disconnection result after the connected ability crashes or is killed. If the Service ability exits unexpectedly, all its connections are disconnected, and each ability previously connected to it will call OnAbilityDisconnectDone(ElementName *elementName, int resultCode, void *data).

Parameters:

	Description
elementName	Indicates the pointer to the information about the disconnected Service ability.
resultCode	Indicates the disconnection result code. The value 0 indicates a successful disconnection, and any other value indicates a disconnection failure.
data	Indicates the pointer to the data stored during the connection.