include/app_manager.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_APP_MANAGER_H
  19 #define __TIZEN_APPFW_APP_MANAGER_H
  20
  21 #include <tizen.h>
  22
  23 #include <app_context.h>
  24 #include <app_info.h>
  25
  26 #include <app_manager_deprecated.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * @addtogroup CAPI_APPLICATION_MANAGER_MODULE
  34  * @{
  35  */
  36
  37
  38 /**
  39  * @brief Enumerations of error code for Application Manager.
  40  */
  41 typedef enum
  42 {
  43         APP_MANAGER_ERROR_NONE = TIZEN_ERROR_NONE,      /**< Successful */
  44         APP_MANAGER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  45         APP_MANAGER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  46         APP_MANAGER_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
  47         APP_MANAGER_ERROR_NO_SUCH_APP = TIZEN_ERROR_APPLICATION_CLASS | 0x01, /**< No such application */
  48
  49         APP_MANAGER_ERROR_DB_FAILED = TIZEN_ERROR_APPLICATION_CLASS | 0x03, /**< Database error  */
  50         APP_MANAGER_ERROR_INVALID_PACKAGE = TIZEN_ERROR_APPLICATION_CLASS | 0x04, /**< Invalid package name */
  51 } app_manager_error_e;
  52
  53
  54 /**
  55  * @brief Called when an application gets launched or termiated.
  56  * @param[in] app_context The application context of the application launched or termiated
  57  * @param[in] event The application context event
  58  * @param[in] user_data The user data passed from the foreach function
  59  * @pre This function is called when an application gets launched or terminated after you register this callback using app_manager_set_app_context_event_cb()
  60  * @see app_manager_set_app_context_event_cb()
  61  * @see app_manager_unset_app_context_event_cb()
  62  */
  63 typedef void (*app_manager_app_context_event_cb) (app_context_h app_context, app_context_event_e event, void *user_data);
  64
  65
  66 /**
  67  * @brief Called to get the application context once for each running application.
  68  * @param[in] app_context The application context of each running application
  69  * @param[in] user_data The user data passed from the foreach function
  70  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  71  * @pre app_manager_foreach_app_context() will invoke this callback.
  72  * @see app_manager_foreach_app_context()
  73  */
  74 typedef bool (*app_manager_app_context_cb) (app_context_h app_context, void *user_data);
  75
  76
  77 /**
  78  * @internal
  79  * @brief Called when an application gets installed, terminated or updated.
  80  * @param[in] app_info The application information of the application installed, terminated or updated
  81  * @param[in] event The application information event
  82  * @param[in] user_data The user data passed from the foreach function
  83  * @pre This function is called when an application gets installed, uninstalled or updated after you register this callback using app_manager_set_app_info_event_cb()
  84  * @see app_manager_set_app_info_event_cb()
  85  * @see app_manager_unset_app_info_event_cb()
  86  */
  87 typedef void (*app_manager_app_info_event_cb) (app_info_h app_info, app_info_event_e event, void *user_data);
  88
  89
  90 /**
  91  * @internal
  92  * @brief Called to get the application information once for each installed application.
  93  * @param[in] app_info The application information of each installed application
  94  * @param[in] user_data The user data passed from the foreach function
  95  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  96  * @pre app_manager_foreach_app_info() will invoke this callback.
  97  * @see app_manager_foreach_app_info()
  98  */
  99 typedef bool (*app_manager_app_info_cb) (app_info_h app_info, void *user_data);
 100
 101
 102 /**
 103  * @brief Registers a callback function to be invoked when the applications gets launched or termiated.
 104  * @param[in] callback The callback function to register
 105  * @param[in] user_data The user data to be passed to the callback function
 106  * @return  0 on success, otherwise a negative error value.
 107  * @retval #APP_MANAGER_ERROR_NONE On Successful
 108  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 109  * @retval #APP_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 110  * @post        It will invoke app_manager_app_context_event_cb() when the application is launched or termiated.
 111  * @see app_manager_unset_app_context_event_cb()
 112  * @see app_manager_app_context_event_cb()
 113  */
 114 int app_manager_set_app_context_event_cb(app_manager_app_context_event_cb callback, void *user_data);
 115
 116
 117 /**
 118  * @brief Unregisters the callback function.
 119  * @return 0 on success, otherwise a negative error value.
 120  * @retval #APP_MANAGER_ERROR_NONE Successful
 121  * @see app_manager_set_app_event_cb()
 122  * @see app_manager_app_context_event_cb()
 123  */
 124 void app_manager_unset_app_context_event_cb(void);
 125
 126
 127 /**
 128  * @brief Retrieves all application contexts of running applications
 129  * @param [in] callback The callback function to invoke
 130  * @param [in] user_data The user data to be passed to the callback function
 131  * @return 0 on success, otherwise a negative error value.
 132  * @retval #APP_MANAGER_ERROR_NONE Successful
 133  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 134  * @post        This function invokes app_manager_app_context_cb() repeatedly for each application context.
 135  * @see app_manager_app_context_cb()
 136  */
 137 int app_manager_foreach_app_context(app_manager_app_context_cb callback, void *user_data);
 138
 139
 140 /**
 141  * @brief Gets the application context for the given ID of the application
 142  * @remarks This function returns #APP_MANAGER_ERROR_NO_SUCH_APP if the application with the given application ID is not running \n
 143  * @a app_context must be released with app_context_destroy() by you.
 144  * @param [in] app_id The ID of the application
 145  * @param [out] app_context The application context of the given application ID
 146  * @return 0 on success, otherwise a negative error value.
 147  * @retval #APP_MANAGER_ERROR_NONE Successful
 148  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 149  * @retval #APP_MANAGER_ERROR_DB_FAILED Database error occurred
 150  * @retval #APP_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 151  * @retval #APP_MANAGER_ERROR_NO_SUCH_APP No such application
 152  */
 153 int app_manager_get_app_context(const char *app_id, app_context_h *app_context);
 154
 155
 156 /**
 157  * @brief Gets the name of the application package for the given process ID of the application
 158  * @remark This function is @b deprecated. Use app_manager_get_app_id() instead.
 159  * @remarks This function returns #APP_MANAGER_ERROR_NO_SUCH_APP if the application with the given process ID is not valid \n
 160  * @a package must be released with free() by you.
 161  * @param [in] pid The process ID of the given application
 162  * @param [out] package The package name of the application
 163  * @return 0 on success, otherwise a negative error value.
 164  * @retval #APP_MANAGER_ERROR_NONE Successful
 165  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @retval #APP_MANAGER_ERROR_DB_FAILED Database error occurred
 167  * @retval #APP_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 168  * @retval #APP_MANAGER_ERROR_NO_SUCH_APP No such application
 169  */
 170 int app_manager_get_package(pid_t pid, char **package);
 171
 172
 173 /**
 174  * @brief Gets the ID of the application for the given process ID
 175  * @remarks This function returns #APP_MANAGER_ERROR_NO_SUCH_APP if the application with the given process ID is not valid \n
 176  * @a app_id must be released with free() by you.
 177  * @param [in] pid The process ID of the application
 178  * @param [out] app_id The ID of the application
 179  * @return 0 on success, otherwise a negative error value.
 180  * @retval #APP_MANAGER_ERROR_NONE Successful
 181  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 182  * @retval #APP_MANAGER_ERROR_DB_FAILED Database error occurred
 183  * @retval #APP_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 184  * @retval #APP_MANAGER_ERROR_NO_SUCH_APP No such application
 185  */
 186 int app_manager_get_app_id(pid_t pid, char **app_id);
 187
 188
 189 /**
 190  * @brief Checks whether the application with the given package name is running.
 191  * @param [in] app_id The ID of the application
 192  * @param [out] running @c true if the application is running, \n @c false if not running.
 193  * @return 0 on success, otherwise a negative error value.
 194  * @retval #APP_MANAGER_ERROR_NONE Successful
 195  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 196  */
 197 int app_manager_is_running(const char *app_id, bool *running);
 198
 199
 200 /**
 201  * @brief Resume the application
 202  * @param [in] app_context The application context
 203  * @return 0 on success, otherwise a negative error value.
 204  * @retval #APP_MANAGER_ERROR_NONE Successful
 205  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 206  */
 207 int app_manager_resume_app(app_context_h app_context);
 208
 209
 210 /**
 211  * @brief Terminate the application
 212  * @param [in] app_context The application context
 213  * @return 0 on success, otherwise a negative error value.
 214  * @retval #APP_MANAGER_ERROR_NONE Successful
 215  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 216  */
 217 int app_manager_terminate_app(app_context_h app_context);
 218
 219
 220 /**
 221  * @internal
 222  * @brief Registers a callback function to be invoked when the applications gets installed, uninstalled or updated.
 223  * @param[in] callback The callback function to register
 224  * @param[in] user_data The user data to be passed to the callback function
 225  * @return  0 on success, otherwise a negative error value.
 226  * @retval #APP_MANAGER_ERROR_NONE On Successful
 227  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 228  * @retval #APP_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 229  * @post        It will invoke app_manager_app_info_event_cb() when the application gets installed, uninstalled or updated.
 230  * @see app_manager_unset_app_info_event_cb()
 231  * @see app_manager_app_info_event_cb()
 232  */
 233 int app_manager_set_app_info_event_cb(app_manager_app_info_event_cb callback, void *user_data);
 234
 235
 236 /**
 237  * @internal
 238  * @brief Unregisters the callback function.
 239  * @return 0 on success, otherwise a negative error value.
 240  * @retval #APP_MANAGER_ERROR_NONE Successful
 241  * @see app_manager_set_app_info_event_cb()
 242  * @see app_manager_app_info_event_cb()
 243  */
 244 void app_manager_unset_app_info_event_cb(void);
 245
 246
 247 /**
 248  * @internal
 249  * @brief Retrieves all application information of installed applications
 250  * @param [in] callback The callback function to invoke
 251  * @param [in] user_data The user data to be passed to the callback function
 252  * @return 0 on success, otherwise a negative error value.
 253  * @retval #APP_MANAGER_ERROR_NONE Successful
 254  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 255  * @post        This function invokes app_manager_app_info_cb() repeatedly for each application information.
 256  * @see app_manager_app_info_cb()
 257  */
 258 int app_manager_foreach_app_info(app_manager_app_info_cb callback, void *user_data);
 259
 260
 261 /**
 262  * @internal
 263  * @brief Gets the application information for the given application ID
 264  * @remarks @a app_info must be released with app_info_destroy() by you.
 265  * @param [in] app_id The ID of the application
 266  * @param [out] app_info The application information for the given application ID
 267  * @return 0 on success, otherwise a negative error value.
 268  * @retval #APP_MANAGER_ERROR_NONE Successful
 269  * @retval #APP_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 270  * @retval #APP_MANAGER_ERROR_DB_FAILED Database error occurred
 271  * @retval #APP_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 272  */
 273 int app_manager_get_app_info(const char *app_id, app_info_h *app_info);
 274
 275
 276 /**
 277  * @}
 278  */
 279
 280
 281 #ifdef __cplusplus
 282 }
 283 #endif
 284
 285 #endif /* __TIZEN_APPFW_APP_MANAGER_H */
 286