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 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(); 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 Obtains the {@link BundleInfo} of an application based on the specified bundle name. 146 * 147 * @attention Before querying a {@link BundleInfo} object, you should first call <b>memset</b> on the constructed 148 * {@link BundleInfo} object so that each field in it can be properly initialized for carrying the 149 * obtained information. 150 * @param bundleName Indicates the pointer to the name of the application bundle to query. 151 * @param flags Specifies whether the obtained {@link BundleInfo} object can contain {@link AbilityInfo}. The value 152 * <b>1</b> indicates that it can contain {@link AbilityInfo}, and <b>0</b> indicates that it cannot. 153 * @param bundleInfo Indicates the pointer to the obtained {@link BundleInfo} object. 154 * 155 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 156 * {@link AppexecfwkErrors} otherwise. 157 * 158 * @since 1.0 159 * @version 1.0 160 */ 161 uint8_t GetBundleInfo(const char *bundleName, int32_t flags, BundleInfo *bundleInfo); 162 163 /** 164 * @brief Obtains the {@link BundleInfo} of all bundles in the system. 165 * 166 * @param flags Specifies whether each of the obtained {@link BundleInfo} objects can contain {@link AbilityInfo}. 167 * The value <b>1</b> indicates that it can contain {@link AbilityInfo}, and <b>0</b> indicates that 168 * it cannot. 169 * @param bundleInfos Indicates the double pointer to the obtained {@link BundleInfo} objects. 170 * @param len Indicates the pointer to the number of {@link BundleInfo} objects obtained. 171 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 172 * {@link AppexecfwkErrors} otherwise. 173 * 174 * @since 1.0 175 * @version 1.0 176 */ 177 uint8_t GetBundleInfos(const int flags, BundleInfo **bundleInfos, int32_t *len); 178 179 /** 180 * @brief Obtains the {@link BundleInfo} of all keep-alive applications in the system. 181 * 182 * @param bundleInfos Indicates the double pointer to the obtained {@link BundleInfo} objects. 183 * @param len Indicates the pointer to the number of {@link BundleInfo} objects obtained. 184 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 185 * {@link AppexecfwkErrors} otherwise. 186 * 187 * @since 1.0 188 * @version 1.0 189 */ 190 uint8_t QueryKeepAliveBundleInfos(BundleInfo **bundleInfos, int32_t *len); 191 192 /** 193 * @brief Obtains the {@link BundleInfo} of application bundles based on the specified {@link MetaData}. 194 * 195 * @param metaDataKey Indicates the pointer to the metadata name in the {@link MetaData}. 196 * @param bundleInfos Indicates the double pointer to the obtained {@link BundleInfo} objects. 197 * @param len Indicates the pointer to the number of {@link BundleInfo} objects obtained. 198 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 199 * {@link AppexecfwkErrors} otherwise. 200 * 201 * @since 1.0 202 * @version 1.0 203 */ 204 uint8_t GetBundleInfosByMetaData(const char *metaDataKey, BundleInfo **bundleInfos, int32_t *len); 205 206 /** 207 * @brief Obtains the bundle name of an application based on the specified UID. 208 * 209 * @param uid Indicates the UID of the application to query. 210 * @param bundleName Indicates the double pointer to the bundle name of the application. 211 * @return Returns {@link ERR_OK} if this function is successfully called; returns another error code defined in 212 * {@link AppexecfwkErrors} otherwise. 213 * 214 * @since 1.0 215 * @version 1.0 216 */ 217 uint8_t GetBundleNameForUid(int32_t uid, char **bundleName); 218 219 #ifdef OHOS_APPEXECFWK_BMS_BUNDLEMANAGER 220 /** 221 * @brief Check if the specify syscap name is supported by the system. 222 * 223 * @param sysCapName Indicates the syscap name to check. 224 * @return Returns <b>true</b> if syscap name is supported; returns <b>false</b> otherwise. 225 * 226 * @since 4 227 * @version 4 228 */ 229 bool HasSystemCapability(const char *sysCapName); 230 231 /** 232 * @brief Obtains all the system available syscap name. 233 * 234 * @return Returns SystemCapability pointer if this function is successfully called; returns nullptr otherwise. 235 * 236 * @since 4 237 * @version 4 238 */ 239 SystemCapability *GetSystemAvailableCapabilities(); 240 241 /** 242 * @brief Free the system available syscap memory 243 * 244 * @param sysCaps Indicates the pointer to the obtained {@link SystemCapability} objects. 245 * 246 * @since 4 247 * @version 4 248 */ 249 void FreeSystemAvailableCapabilitiesInfo(SystemCapability *sysCap); 250 #endif 251 /** 252 * @brief Get bundle size 253 * 254 * @param bundleName Indicates the bundle name. 255 * @return Returns the bundle size (Byte) if this function is successfully called; returns 0 otherwise. 256 * 257 * @since 7 258 * @version 7 259 */ 260 uint32_t GetBundleSize(const char *bundleName); 261 #ifdef __cplusplus 262 #if __cplusplus 263 } 264 #endif 265 #endif /* __cplusplus */ 266 #endif /* OHOS_BUNDLEMANAGER_INTERFACE_H */ 267 /** @} */