1 /*
2  * Copyright (c) 2020 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 /**
17  * @addtogroup AbilityKit
18  * @{
19  *
20  * @brief Provides ability-related functions, including ability lifecycle callbacks and functions for connecting to or
21  *        disconnecting from Particle Abilities.
22  *
23  * Abilities are classified into Feature Abilities and Particle Abilities. Feature Abilities support the Page template,
24  * and Particle Abilities support the Service template. An ability using the Page template is called a Page ability for
25  * short and that using the Service template is called a Service ability.
26  *
27  * @since 1.0
28  * @version 1.0
29  */
30 
31 /**
32  * @file ability_context.h
33  *
34  * @brief Declares functions for starting and stopping an ability.
35  *
36  * The {@link Ability} and {@link AbilitySlice} classes are inherited from the <b>AbilityContext</b> class for you to
37  * call functions in this class for application development.
38  *
39  * @since 1.0
40  * @version 1.0
41  */
42 
43 #ifndef OHOS_ABILITY_CONTEXT_H
44 #define OHOS_ABILITY_CONTEXT_H
45 
46 #include <ability_manager.h>
47 #include <want.h>
48 #include "ability_connection.h"
49 
50 namespace OHOS {
51 /**
52  * @brief Provides functions for starting and stopping an ability.
53  *
54  * The {@link Ability} and {@link AbilitySlice} classes are inherited from the <b>AbilityContext</b> class for you to
55  * call functions in this class for application development.
56  *
57  * @since 1.0
58  * @version 1.0
59  */
60 class AbilityContext {
61 public:
62     AbilityContext() = default;
63     ~AbilityContext() = default;
64 
65     /**
66      * @brief Starts an {@link Ability} based on the specified {@link Want} information.
67      *
68      * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to
69      *             start.
70      * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise.
71      */
72     int StartAbility(const Want &want);
73 
74     /**
75      * @brief Stops an {@link Ability} based on the specified {@link Want} information.
76      *
77      * This function takes effect only on Service abilities.
78      *
79      * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to
80      *             stop.
81      * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise.
82      */
83     int StopAbility(const Want &want);
84 
85     /**
86      * @brief Destroys this {@link Ability}.
87      *
88      * This function can be called only by this ability.
89      *
90      * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise.
91      */
92     int TerminateAbility();
93 
94     /**
95      * @brief Connects to a Service ability based on the specified {@link Want} information.
96      *
97      * After the Service ability is connected, the Ability Manager Service invokes a particular callback and returns
98      * the ID of the Service ability. The client can use this ID to communicate with the connected Service ability.
99      *
100      * @param want Indicates the pointer to the {@link Want} structure containing information about the Service
101      *             ability to connect.
102      * @param conn Indicates the callback to be invoked when the connection is successful.
103      * @param data Indicates the pointer to the data to be passed to the callback.
104      * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise.
105      */
106     int ConnectAbility(const Want &want, const IAbilityConnection &conn, void *data);
107 
108     /**
109      * @brief Disconnects from a Service ability.
110      *
111      * @param conn Indicates the callback to be invoked when the connection is successful.
112      * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise.
113      */
114     int DisconnectAbility(const IAbilityConnection &conn);
115 
116 private:
117     friend class Ability;
118     friend class AbilitySlice;
119     uint64_t token_ { 0 };
120 };
121 } //  OHOS
122 
123 #endif //  OHOS_ABILITY_CONTEXT_H
124