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.h 33 * 34 * @brief Declares ability-related functions, including ability lifecycle callbacks and functions for connecting to or 35 * disconnecting from Particle Abilities. 36 * 37 * As the fundamental unit of OpenHarmony applications, abilities are classified into Feature Abilities and Particle 38 * Abilities. Feature Abilities support the Page template, and Particle Abilities support the Service template. 39 * An ability using the Page template is called Page ability for short and that using the Service template 40 * is called Service ability. 41 * 42 * @since 1.0 43 * @version 1.0 44 */ 45 #ifndef OHOS_ABILITY_H 46 #define OHOS_ABILITY_H 47 48 #ifdef ABILITY_WINDOW_SUPPORT 49 #include <components/root_view.h> 50 #endif 51 #include <string> 52 53 #include "ability_context.h" 54 #include "ability_manager.h" 55 #include "serializer.h" 56 57 namespace OHOS { 58 #ifdef ABILITY_WINDOW_SUPPORT 59 class AbilitySliceManager; 60 class AbilityWindow; 61 #endif 62 63 /** 64 * @brief Declares ability-related functions, including ability lifecycle callbacks and functions for connecting to or 65 * disconnecting from Particle Abilities. 66 * 67 * As the fundamental unit of OpenHarmony applications, abilities are classified into Feature Abilities and Particle 68 * Abilities. Feature Abilities support the Page template, and Particle Abilities support the Service template. 69 * An ability using the Page template is called Page ability for short and that using the Service template 70 * is called Service ability. 71 * 72 * @since 1.0 73 * @version 1.0 74 */ 75 class Ability : public AbilityContext { 76 public: 77 Ability() = default; 78 virtual ~Ability() = default; 79 80 /** 81 * @brief Called when this ability is started. You must override this function if you want to perform some 82 * initialization operations during ability startup. 83 * 84 * This function can be called only once in the entire lifecycle of an ability. 85 * @param want Indicates the {@link Want} structure containing startup information about the ability. 86 */ 87 virtual void OnStart(const Want &want); 88 89 /** 90 * @brief Called when this ability enters the <b>STATE_INACTIVE</b> state. 91 * 92 * <b>STATE_INACTIVE</b> is an instantaneous state. The ability in this state may be visible but does not have 93 * focus. You can override this function to implement your own processing logic. 94 */ 95 virtual void OnInactive(); 96 97 /** 98 * @brief Called when this ability enters the <b>STATE_ACTIVE</b> state. 99 * 100 * The ability in the <b>STATE_ACTIVE</b> state is visible and has focus. 101 * You can override this function to implement your own processing logic. 102 * 103 * @param want Indicates the {@link Want} structure containing activation information about the ability. 104 */ 105 virtual void OnActive(const Want &want); 106 107 /** 108 * @brief Called when this ability enters the <b>STATE_BACKGROUND</b> state. 109 * 110 * 111 * The ability in the <b>STATE_BACKGROUND</b> state is invisible. 112 * You can override this function to implement your own processing logic. 113 */ 114 virtual void OnBackground(); 115 116 /** 117 * @brief Called when this ability enters the <b>STATE_STOP</b> state. 118 * 119 * The ability in the <b>STATE_STOP</b> is being destroyed. 120 * You can override this function to implement your own processing logic. 121 */ 122 virtual void OnStop(); 123 124 /** 125 * @brief Called when this Service ability is connected for the first time. 126 * 127 * You can override this function to implement your own processing logic. 128 * 129 * @param want Indicates the {@link Want} structure containing connection information about the Service ability. 130 * @return Returns a pointer to the <b>sid</b> of the connected Service ability. 131 */ 132 virtual const SvcIdentity *OnConnect(const Want &want); 133 134 /** 135 * @brief Called when all abilities connected to this Service ability are disconnected. 136 * 137 * You can override this function to implement your own processing logic. 138 * 139 * @param want Indicates the {@link Want} structure containing disconnection information about the Service 140 * ability. 141 */ 142 virtual void OnDisconnect(const Want &want); 143 144 #ifdef ABILITY_WINDOW_SUPPORT 145 /** 146 * @brief Sets the main route for this ability. 147 * 148 * The main route, also called main entry, refers to the default <b>AbilitySlice</b> to present for this ability. 149 * This function should be called only on Feature Abilities. If this function is not called in the 150 * {@link OnStart(const Want &want)} function for a Feature Ability, the Feature Ability will fail to start. 151 * 152 * @param entry Indicates the main entry, which is the class name of the <b>AbilitySlice</b> instance to start. 153 */ 154 void SetMainRoute(const std::string &entry); 155 156 /** 157 * @brief Sets the UI layout for this ability. 158 * You can call {@link GetWindowRootView()} to create a layout and add controls. 159 * 160 * @param rootView Indicates the pointer to the custom layout view you have created. 161 */ 162 void SetUIContent(RootView *rootView); 163 #endif 164 /** 165 * @brief Handles a message sent by the client to this Service ability. 166 * 167 * @param funcId Indicates the type of the message sent by the client. 168 * @param request Indicates the pointer to the serialized request parameters sent by the client. 169 * @param reply Indicates the pointer to the serialized result returned to the client. 170 */ 171 virtual void MsgHandle(uint32_t funcId, IpcIo *request, IpcIo *reply); 172 173 /** 174 * @brief Prints ability information to the console. 175 * 176 * You can override this function to obtain or print extra parameters. 177 * 178 * @param extra Indicates the extra parameter to be obtained or printed to the console. 179 */ 180 virtual void Dump(const std::string &extra); 181 182 private: 183 typedef enum { 184 START, 185 INACTIVE, 186 ACTIVE, 187 BACKGROUND, 188 STOP, 189 } Action; 190 191 void Init(uint64_t token, int abilityType, bool isNativeApp); 192 int GetState() const; 193 std::string GetDumpInfo() const; 194 #ifdef ABILITY_WINDOW_SUPPORT 195 void DeliverAbilityLifecycle(Action action, const Want *want = nullptr); 196 #endif 197 static int32_t MsgHandleInner(const IpcContext* context, void *ipcMsg, IpcIo *data, void *arg); 198 199 #ifdef ABILITY_WINDOW_SUPPORT 200 AbilitySliceManager *abilitySliceManager_ { nullptr }; 201 AbilityWindow *abilityWindow_ { nullptr }; 202 #endif 203 int abilityState_ { 0 }; 204 int abilityType_ { 0 }; 205 uint64_t token_ { 0 }; 206 SvcIdentity *sid_ { nullptr }; 207 static const int MAX_OBJECTS = 6; 208 209 friend class AbilityThread; 210 #ifdef ABILITY_WINDOW_SUPPORT 211 friend class AbilitySliceManager; 212 #endif 213 }; 214 } // namespace OHOS 215 #endif // OHOS_ABILITY_H 216