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_manager.h 33 * 34 * @brief Declares ability-related functions, including functions for starting, stopping, connecting to, 35 * and disconnecting from an ability, registering a callback, and unregistering a callback. 36 * 37 * @since 1.0 38 * @version 1.0 39 */ 40 #ifndef OHOS_ABILITY_MANAGER_H 41 #define OHOS_ABILITY_MANAGER_H 42 43 #include "ability_connection.h" 44 #include "want.h" 45 46 #ifdef __cplusplus 47 #if __cplusplus 48 extern "C" { 49 #endif 50 #endif /* __cplusplus */ 51 52 /** 53 * @brief Called when desired ability has been started. 54 * 55 * This function can be registered through {@link StartAbility} to receive the start ability result. 56 * 57 * @param resultCode Indicates the status code returned for starting ability result. For details, 58 * see {@link AppexecfwkErrors}. 59 * @param resultMessage Indicates the result message returned with the status code. 60 * 61 */ 62 typedef void (*IAbilityStartCallback)(const uint8_t resultCode, const void *resultMessage); 63 64 /** 65 * @brief Starts an ability based on the specified {@link Want} information. 66 * 67 * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to start. 68 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 69 */ 70 int StartAbility(const Want *want); 71 72 /** 73 * @brief Starts an ability based on the specified {@link Want} information with specific callback 74 * {@link IAbilityStartCallback}. 75 * 76 * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to start. 77 * @param iAbilityStartCallback callback to be invoked when finishing starting ability. 78 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 79 */ 80 int StartAbilityWithCallback(const Want *want, IAbilityStartCallback iAbilityStartCallback); 81 82 /** 83 * @brief Stops an ability based on the specified {@link Want} information. 84 * 85 * This function takes effect only on Service abilities. 86 * 87 * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to stop. 88 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 89 */ 90 int StopAbility(const Want *want); 91 92 /** 93 * @brief Connects to a Service ability based on the specified {@link Want} information. 94 * 95 * @param want Indicates the pointer to the {@link Want} structure containing 96 * information about the Service ability to connect. 97 * @param conn Indicates the callback object when the Service ability is connected. 98 * @param data Indicates the pointer to the data to be passed to the callback. 99 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 100 */ 101 int ConnectAbility(const Want *want, const IAbilityConnection *conn, void *data); 102 103 /** 104 * @brief Disconnects from a Service ability. 105 * 106 * @param conn Indicates the callback object when the Service ability is connected. 107 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 108 */ 109 int DisconnectAbility(const IAbilityConnection *conn); 110 111 #ifdef __cplusplus 112 #if __cplusplus 113 } 114 #endif 115 #endif /* __cplusplus */ 116 #endif /* OHOS_ABILITY_MANAGER_H */ 117