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, see {@link AppexecfwkErrors}. 58 * @param resultMessage Indicates the result message returned with the status code. 59 * 60 */ 61 typedef void (*IAbilityStartCallback)(const uint8_t resultCode, const void *resultMessage); 62 63 /** 64 * @brief Starts an ability based on the specified {@link Want} information. 65 * 66 * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to start. 67 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 68 */ 69 int StartAbility(const Want *want); 70 71 /** 72 * @brief Starts an ability based on the specified {@link Want} information with specific callback {@link IAbilityStartCallback}. 73 * 74 * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to start. 75 * @param iAbilityStartCallback callback to be invoked when finishing starting ability. 76 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 77 */ 78 int StartAbilityWithCallback(const Want *want, IAbilityStartCallback iAbilityStartCallback); 79 80 /** 81 * @brief Stops an ability based on the specified {@link Want} information. 82 * 83 * This function takes effect only on Service abilities. 84 * 85 * @param want Indicates the pointer to the {@link Want} structure containing information about the ability to stop. 86 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 87 */ 88 int StopAbility(const Want *want); 89 90 /** 91 * @brief Connects to a Service ability based on the specified {@link Want} information. 92 * 93 * @param want Indicates the pointer to the {@link Want} structure containing 94 * information about the Service ability to connect. 95 * @param conn Indicates the callback object when the Service ability is connected. 96 * @param data Indicates the pointer to the data to be passed to the callback. 97 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 98 */ 99 int ConnectAbility(const Want *want, const IAbilityConnection *conn, void *data); 100 101 /** 102 * @brief Disconnects from a Service ability. 103 * 104 * @param conn Indicates the callback object when the Service ability is connected. 105 * @return Returns <b>0</b> if this function is successfully called; returns another value otherwise. 106 */ 107 int DisconnectAbility(const IAbilityConnection *conn); 108 109 #ifdef __cplusplus 110 #if __cplusplus 111 } 112 #endif 113 #endif /* __cplusplus */ 114 #endif /* OHOS_ABILITY_MANAGER_H */ 115