1 /* 2 * Copyright (c) 2020-2023 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 BundleManager 18 * @{ 19 * 20 * @brief Provides structures and functions for managing application bundles and obtaining application information. 21 * 22 * You can use functions provided by this module to install, update, or uninstall an application, obtain 23 * {@link AbilityInfo} and {@link BundleInfo} about an application, and obtain the bundle name of an application 24 * based on the application's user ID (UID). 25 * 26 * @since 1.0 27 * @version 1.0 28 */ 29 30 /** 31 * @file bundle_manager.h 32 * 33 * @brief Declares functions used for managing application bundles and obtaining bundle information. 34 * 35 * You can use functions provided in this file to install, update, or uninstall an application, obtain 36 * {@link AbilityInfo} and {@link BundleInfo} about an application, obtain the bundle name of an application based 37 * on the application's user ID (UID), and obtain {@link BundleInfo} objects of all applications or keep-alive 38 * applications in the system. 39 * 40 * @since 1.0 41 * @version 1.0 42 */ 43 #ifndef OHOS_BUNDLEMANAGER_INTERFACE_H 44 #define OHOS_BUNDLEMANAGER_INTERFACE_H 45 46 #include "ability_info.h" 47 #include "bundle_info.h" 48 #include "bundle_status_callback.h" 49 #include "install_param.h" 50 #include "stdint.h" 51 #include "want.h" 52 53 #ifdef __cplusplus 54 #if __cplusplus 55 extern "C" { 56 #endif 57 #endif /* __cplusplus */ 58 59 /** 60 * @brief Called when an application is installed, updated, or uninstalled. 61 * 62 * This function can be registered through {@link Install} and {@link Uninstall} to receive the installation, update, 63 * and uninstallation result. 64 * 65 * @param resultCode Indicates the status code returned for the application installation, update, or uninstallation 66 * result. For details, see {@link AppexecfwkErrors}. 67 * @param resultMessage Indicates the result message returned with the status code. 68 * 69 * @since 1.0 70 * @version 1.0 71 */ 72 typedef void (*InstallerCallback)(const uint8_t resultCode, const void *resultMessage); 73 74 /** 75 * @brief Registers a callback to monitor the installation, update, and uninstallation state changes of an application. 76 * 77 * @param BundleStatusCallback Indicates the pointer to the callback to be invoked when the installation, update, or 78 * uninstallation state of the monitored application changes. 79 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 80 * {@link AppexecfwkErrors} otherwise. 81 * 82 * @since 1.0 83 * @version 1.0 84 */ 85 int32_t RegisterCallback(BundleStatusCallback *BundleStatusCallback); 86 87 /** 88 * @brief Unregisters a callback previously registered for monitoring the installation, update, and uninstallation stat 89 * changes of an application. 90 * 91 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 92 * {@link AppexecfwkErrors} otherwise. 93 * 94 * @since 1.0 95 * @version 1.0 96 */ 97 int32_t UnregisterCallback(void); 98 99 /** 100 * @brief Installs or updates an application. 101 * 102 * 103 * @param hapPath Indicates the pointer to the path for storing the OpenHarmony Ability Package (HAP) of the application 104 * to install or update. 105 * @param installParam Indicates the pointer to the parameters used for application installation or update. 106 * @param installerCallback Indicates the callback to be invoked for notifying the installation or update result. 107 * @return Returns <b>true</b> if this function is successfully called; returns <b>false</b> otherwise. 108 * 109 * @since 1.0 110 * @version 1.0 111 */ 112 bool Install(const char *hapPath, const InstallParam *installParam, InstallerCallback installerCallback); 113 114 /** 115 * @brief Uninstalls an application. 116 * 117 * @param bundleName Indicates the pointer to the bundle name of the application to uninstall. 118 * @param installParam Indicates the pointer to the parameters used for application uninstallation. 119 * @param installerCallback Indicates the callback to be invoked for notifying the uninstallation result. 120 * @return Returns <b>true</b> if this function is successfully called; returns <b>false</b> otherwise. 121 * 122 * @since 1.0 123 * @version 1.0 124 */ 125 bool Uninstall(const char *bundleName, const InstallParam *installParam, InstallerCallback installerCallback); 126 127 /** 128 * @brief Queries the {@link AbilityInfo} of an ability based on the information carried in the {@link Want} 129 * structure. 130 * @attention Before querying an {@link AbilityInfo} object, you should first call <b>memset</b> on the 131 * constructed {@link AbilityInfo} object so that each field in it can be properly initialized 132 * for carrying the obtained information. 133 * @param want Indicates the pointer to the {@link Want} structure used for querying the specified ability. 134 * @param abilityInfo Indicates the pointer to the obtained {@link AbilityInfo} object. 135 * 136 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 137 * {@link AppexecfwkErrors} otherwise. 138 * 139 * @since 1.0 140 * @version 1.0 141 */ 142 uint8_t QueryAbilityInfo(const Want *want, AbilityInfo *abilityInfo); 143 144 /** 145 * @brief Query qualified abilityInfo according to want. 146 * 147 * @param want The want provided by ActivityManagerService contains the actions fiels you want to query. 148 * @param abilityInfo Qualified abilityInfo. 149 * @param len Indicates the pointer to the number of {@link abilityInfo} objects obtained. 150 * @return Returns {@link ERR_OK} if this function is successfully called; 151 */ 152 uint8_t QueryAbilityInfos(const Want *want, AbilityInfo **abilityInfo, int32_t *len); 153 154 /** 155 * @brief Register an event callback to return the specified HCE tag. 156 * 157 * @param installerCallback callback function. 158 * @return Returns result if this function is successfully called; 159 */ 160 bool RegisterEvent(InstallerCallback installerCallback); 161 162 /** 163 * @brief Unregister an event callback, which is used to cancel the RegisterEvent. 164 * 165 * @param installerCallback callback function. 166 * @return Returns result if this function is successfully called; 167 */ 168 bool UnregisterEvent(InstallerCallback installerCallback); 169 170 /** 171 * @brief Obtains the {@link BundleInfo} of an application based on the specified bundle name. 172 * 173 * @attention Before querying a {@link BundleInfo} object, you should first call <b>memset</b> on the constructed 174 * {@link BundleInfo} object so that each field in it can be properly initialized for carrying the 175 * obtained information. 176 * @param bundleName Indicates the pointer to the name of the application bundle to query. 177 * @param flags Specifies whether the obtained {@link BundleInfo} object can contain {@link AbilityInfo}. The value 178 * <b>1</b> indicates that it can contain {@link AbilityInfo}, and <b>0</b> indicates that it cannot. 179 * @param bundleInfo Indicates the pointer to the obtained {@link BundleInfo} object. 180 * 181 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 182 * {@link AppexecfwkErrors} otherwise. 183 * 184 * @since 1.0 185 * @version 1.0 186 */ 187 uint8_t GetBundleInfo(const char *bundleName, int32_t flags, BundleInfo *bundleInfo); 188 189 /** 190 * @brief Obtains the {@link BundleInfo} of all bundles in the system. 191 * 192 * @param flags Specifies whether each of the obtained {@link BundleInfo} objects can contain {@link AbilityInfo}. 193 * The value <b>1</b> indicates that it can contain {@link AbilityInfo}, and <b>0</b> indicates that 194 * it cannot. 195 * @param bundleInfos Indicates the double pointer to the obtained {@link BundleInfo} objects. 196 * @param len Indicates the pointer to the number of {@link BundleInfo} objects obtained. 197 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 198 * {@link AppexecfwkErrors} otherwise. 199 * 200 * @since 1.0 201 * @version 1.0 202 */ 203 uint8_t GetBundleInfos(const int flags, BundleInfo **bundleInfos, int32_t *len); 204 205 /** 206 * @brief Obtains the {@link BundleInfo} of all keep-alive applications in the system. 207 * 208 * @param bundleInfos Indicates the double pointer to the obtained {@link BundleInfo} objects. 209 * @param len Indicates the pointer to the number of {@link BundleInfo} objects obtained. 210 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 211 * {@link AppexecfwkErrors} otherwise. 212 * 213 * @since 1.0 214 * @version 1.0 215 */ 216 uint8_t QueryKeepAliveBundleInfos(BundleInfo **bundleInfos, int32_t *len); 217 218 /** 219 * @brief Obtains the {@link BundleInfo} of application bundles based on the specified {@link MetaData}. 220 * 221 * @param metaDataKey Indicates the pointer to the metadata name in the {@link MetaData}. 222 * @param bundleInfos Indicates the double pointer to the obtained {@link BundleInfo} objects. 223 * @param len Indicates the pointer to the number of {@link BundleInfo} objects obtained. 224 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 225 * {@link AppexecfwkErrors} otherwise. 226 * 227 * @since 1.0 228 * @version 1.0 229 */ 230 uint8_t GetBundleInfosByMetaData(const char *metaDataKey, BundleInfo **bundleInfos, int32_t *len); 231 232 /** 233 * @brief Obtains the bundle name of an application based on the specified UID. 234 * 235 * @param uid Indicates the UID of the application to query. 236 * @param bundleName Indicates the double pointer to the bundle name of the application. 237 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 238 * {@link AppexecfwkErrors} otherwise. 239 * 240 * @since 1.0 241 * @version 1.0 242 */ 243 uint8_t GetBundleNameForUid(int32_t uid, char **bundleName); 244 245 #ifdef OHOS_APPEXECFWK_BMS_BUNDLEMANAGER 246 /** 247 * @brief Check if the specify syscap name is supported by the system. 248 * 249 * @param sysCapName Indicates the syscap name to check. 250 * @return Returns <b>true</b> if syscap name is supported; returns <b>false</b> otherwise. 251 * 252 * @since 4 253 * @version 4 254 */ 255 bool HasSystemCapability(const char *sysCapName); 256 257 /** 258 * @brief Obtains all the system available syscap name. 259 * 260 * @return Returns SystemCapability pointer if this function is successfully called; returns nullptr otherwise. 261 * 262 * @since 4 263 * @version 4 264 */ 265 SystemCapability *GetSystemAvailableCapabilities(); 266 267 /** 268 * @brief Free the system available syscap memory 269 * 270 * @param sysCaps Indicates the pointer to the obtained {@link SystemCapability} objects. 271 * 272 * @since 4 273 * @version 4 274 */ 275 void FreeSystemAvailableCapabilitiesInfo(SystemCapability *sysCap); 276 #endif 277 /** 278 * @brief Get bundle size 279 * 280 * @param bundleName Indicates the bundle name. 281 * @return Returns the bundle size (Byte) if this function is successfully called; returns 0 otherwise. 282 * 283 * @since 7 284 * @version 7 285 */ 286 uint32_t GetBundleSize(const char *bundleName); 287 #ifdef __cplusplus 288 #if __cplusplus 289 } 290 #endif 291 #endif /* __cplusplus */ 292 #endif /* OHOS_BUNDLEMANAGER_INTERFACE_H */ 293 /** @} */