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 #ifndef __TIZEN_APPFW_APP_MANAGER_H
  18 #define __TIZEN_APPFW_APP_MANAGER_H
  19
  20 #include <tizen.h>
  21
  22 #include <app_context.h>
  23 #include <app_info.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @file app_manager.h
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_APPLICATION_MANAGER_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Enumerations for Application Manager Error .
  40  * @since_tizen 2.3
  41  */
  42 typedef enum
  43 {
  44     APP_MANAGER_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  45     APP_MANAGER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  46     APP_MANAGER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  47     APP_MANAGER_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
  48     APP_MANAGER_ERROR_NO_SUCH_APP = TIZEN_ERROR_APPLICATION_MANAGER | 0x01, /**< No such application */
  49
  50     APP_MANAGER_ERROR_DB_FAILED = TIZEN_ERROR_APPLICATION_MANAGER | 0x03, /**< Database error  */
  51     APP_MANAGER_ERROR_INVALID_PACKAGE = TIZEN_ERROR_APPLICATION_MANAGER | 0x04, /**< Invalid package name */
  52     APP_MANAGER_ERROR_APP_NO_RUNNING = TIZEN_ERROR_APPLICATION_MANAGER | 0x05, /**< App is not running */
  53     APP_MANAGER_ERROR_REQUEST_FAILED = TIZEN_ERROR_APPLICATION_MANAGER | 0x06, /**< Internal aul request error */
  54     APP_MANAGER_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED /**< Permission denied */
  55 } app_manager_error_e;
  56
  57 /**
  58  * @internal
  59  * @brief  Called when an application is launched or terminated.
  60  * @since_tizen 2.3
  61  * @param[in]   app_context  The application context of the application launched or terminated
  62  * @param[in]   event        The application context event
  63  * @param[in]   user_data    The user data passed from the foreach function
  64  * @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().
  65  * @see app_manager_set_app_context_event_cb()
  66  * @see app_manager_unset_app_context_event_cb()
  67  */
  68 typedef void (*app_manager_app_context_event_cb) (app_context_h app_context, app_context_event_e event, void *user_data);
  69
  70 /**
  71  * @brief  Called to get the application context once for each running application.
  72  * @since_tizen 2.3
  73  * @param[in]   app_context  The application context of each running application
  74  * @param[in]   user_data    The user data passed from the foreach function
  75  * @return      @c true to continue with the next iteration of the loop, \n
  76  *              otherwise @c false to break out of the loop
  77  * @pre app_manager_foreach_app_context() will invoke this callback.
  78  * @see app_manager_foreach_app_context()
  79  */
  80 typedef bool (*app_manager_app_context_cb) (app_context_h app_context, void *user_data);
  81
  82 /**
  83  * @brief  Called to get the application information once for each installed application.
  84  * @since_tizen 2.3
  85  * @param[in]   app_info   The application information of each installed application
  86  * @param[in]   user_data  The user data passed from the foreach function
  87  * @return      @c true to continue with the next iteration of the loop, \n
  88  *              otherwise @c false to break out of the loop
  89  * @pre app_manager_foreach_app_info() will invoke this callback.
  90  * @see app_manager_foreach_app_info()
  91  */
  92 typedef bool (*app_manager_app_info_cb) (app_info_h app_info, void *user_data);
  93
  94 /**
  95  * @internal
  96  * @brief  Registers a callback function to be invoked when the applications get launched or terminated.
  97  * @since_tizen 2.3
  98  * @privlevel public
  99  * @privilege %http://tizen.org/privilege/packagemanager.info
 100  * @param[in]   callback   The callback function to register
 101  * @param[in]   user_data  The user data to be passed to the callback function
 102  * @return      @c 0 on success,
 103  *              otherwise a negative error value
 104  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 105  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 106  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 107  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 108  * @post It will invoke app_manager_app_context_event_cb() when the application is launched or terminated.
 109  * @see app_manager_unset_app_context_event_cb()
 110  * @see app_manager_app_context_event_cb()
 111  */
 112 int app_manager_set_app_context_event_cb(app_manager_app_context_event_cb callback, void *user_data);
 113
 114 /**
 115  * @internal
 116  * @brief   Unregisters the callback function.
 117  * @since_tizen 2.3
 118  * @see app_manager_set_app_event_cb()
 119  * @see app_manager_app_context_event_cb()
 120  */
 121 void app_manager_unset_app_context_event_cb(void);
 122
 123 /**
 124  * @brief  Retrieves all application contexts of running applications.
 125  * @since_tizen 2.3
 126  * @privlevel public
 127  * @privilege %http://tizen.org/privilege/packagemanager.info
 128  * @param[in]   callback   The callback function to invoke
 129  * @param[in]   user_data  The user data to be passed to the callback function
 130  * @return      @c 0 on success,
 131  *              otherwise a negative error value
 132  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 133  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 134  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 135  * @post   This function invokes app_manager_app_context_cb() for each application context.
 136  * @see app_manager_app_context_cb()
 137  */
 138 int app_manager_foreach_app_context(app_manager_app_context_cb callback, void *user_data);
 139
 140 /**
 141  * @brief  Gets the application context for the given ID of the application.
 142  * @since_tizen 2.3
 143  * @privlevel public
 144  * @privilege %http://tizen.org/privilege/packagemanager.info
 145  * @remarks  This function returns #APP_MANAGER_ERROR_NO_SUCH_APP if the application with the given application ID is not running. \n
 146  *           You must release @a app_context using app_context_destroy().
 147  * @param[in]   app_id       The ID of the application
 148  * @param[out]  app_context  The application context of the given application ID
 149  * @return      @c 0 on success,
 150  *              otherwise a negative error value
 151  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 152  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 153  * @retval  #APP_MANAGER_ERROR_DB_FAILED          Database error occurred
 154  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 155  * @retval  #APP_MANAGER_ERROR_NO_SUCH_APP        No such application
 156  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 157  */
 158 int app_manager_get_app_context(const char *app_id, app_context_h *app_context);
 159
 160 /**
 161  * @brief  Gets the ID of the application for the given process ID.
 162  * @since_tizen 2.3
 163  * @privlevel public
 164  * @privilege %http://tizen.org/privilege/packagemanager.info
 165  * @remarks  This function returns #APP_MANAGER_ERROR_NO_SUCH_APP if the application with the given process ID is not valid. \n
 166  *           You must release @a app_id using free().
 167  * @param[in]   pid     The process ID of the application
 168  * @param[out]  app_id  The ID of the application
 169  * @return      @c 0 on success,
 170  *              otherwise a negative error value
 171  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 172  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 173  * @retval  #APP_MANAGER_ERROR_DB_FAILED          Database error occurred
 174  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 175  * @retval  #APP_MANAGER_ERROR_NO_SUCH_APP        No such application
 176  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 177  */
 178 int app_manager_get_app_id(pid_t pid, char **app_id);
 179
 180 /**
 181  * @brief  Checks whether the application with the given package name is running.
 182  * @since_tizen 2.3
 183  * @param[in]   app_id   The ID of the application
 184  * @param[out]  running  @c true if the application is running, \n
 185  *                       otherwise @c false if not running
 186  * @return      @c 0 on success,
 187  *              otherwise a negative error value
 188  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 189  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 190  */
 191 int app_manager_is_running(const char *app_id, bool *running);
 192
 193 /**
 194  * @brief  Resumes the application.
 195  * @since_tizen 2.3
 196  * @privlevel public
 197  * @privilege %http://tizen.org/privilege/appmanager.launch
 198  * @param[in]   app_context  The application context
 199  * @return      @c 0 on success,
 200  *              otherwise a negative error value
 201  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 202  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 203  * @retval  #APP_MANAGER_ERROR_APP_NO_RUNNING  App is not running
 204  * @retval  #APP_MANAGER_ERROR_REQUEST_FAILED  Internal resume error
 205  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 206  */
 207 int app_manager_resume_app(app_context_h app_context);
 208
 209 /**
 210  * @internal
 211  * @brief  Opens the application.
 212  * @since_tizen 2.3
 213  * @privlevel public
 214  * @privilege %http://tizen.org/privilege/appmanager.launch
 215  * @param[in]   app_id  The ID of the application
 216  * @return      @c 0 on success,
 217  *              otherwise a negative error value
 218  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 219  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 220  * @retval  #APP_MANAGER_ERROR_NO_SUCH_APP  No such application
 221  * @retval  #APP_MANAGER_ERROR_REQUEST_FAILED  Internal open error
 222  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 223  */
 224 int app_manager_open_app(const char *app_id);
 225
 226 /**
 227  * @internal
 228  * @brief  Terminates the application.
 229  * @since_tizen 2.3
 230  * @privlevel platform
 231  * @privilege %http://tizen.org/privilege/appmanager.kill
 232  * @param[in]   app_context  The application context
 233  * @return      @c 0 on success,
 234  *              otherwise a negative error value
 235  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 236  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 237  * @retval  #APP_MANAGER_ERROR_REQUEST_FAILED  Internal terminate error
 238  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 239  */
 240 int app_manager_terminate_app(app_context_h app_context);
 241
 242 /**
 243  * @brief  Retrieves all installed applications information.
 244  * @since_tizen 2.3
 245  * @privlevel public
 246  * @privilege %http://tizen.org/privilege/packagemanager.info
 247  * @param[in]   callback   The callback function to invoke
 248  * @param[in]   user_data  The user data to be passed to the callback function
 249  * @return      @c 0 on success,
 250  *              otherwise a negative error value
 251  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 252  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 253  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 254  * @post    This function invokes app_manager_app_info_cb() for each application information.
 255  * @see app_manager_app_info_cb()
 256  */
 257 int app_manager_foreach_app_info(app_manager_app_info_cb callback, void *user_data);
 258
 259 /**
 260  * @brief  Gets the application information for the given application ID.
 261  * @since_tizen 2.3
 262  * @privlevel public
 263  * @privilege %http://tizen.org/privilege/packagemanager.info
 264  * @remarks     You must release @a app_info using app_info_destroy().
 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      @c 0 on success,
 268  *              otherwise a negative error value
 269  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 270  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 271  * @retval  #APP_MANAGER_ERROR_DB_FAILED          Database error occurred
 272  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 273  * @retval #APP_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 274  */
 275 int app_manager_get_app_info(const char *app_id, app_info_h *app_info);
 276
 277 /**
 278  * @brief  Gets the absolute path to the shared data directory of the application specified
 279  *         with an application ID.
 280  * @details     An application can only read the files of other application's shared data directory.
 281  * @since_tizen 2.3
 282  * @remarks     The specified @a path should be released.
 283  *
 284  * @param[in]      app_id  The ID of the application
 285  * @param[in,out]  path    The absolute path to the shared data directory of the application
 286  *                         specified with the @a app_id
 287  * @return  @c 0 on success,
 288  *          otherwise a negative error value
 289  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 290  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 291  * @retval  #APP_MANAGER_ERROR_NO_SUCH_APP        No such application
 292  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 293  */
 294 int app_manager_get_shared_data_path(const char *app_id, char **path);
 295
 296 /**
 297  * @brief  Gets the absolute path to the shared resource directory of the application specified
 298  *         with an application ID.
 299  * @details     An application can only read the files of other application's shared resource directory.
 300  * @since_tizen 2.3
 301  * @remarks     The specified @a path should be released.
 302  *
 303  * @param[in]      app_id  The ID of the application
 304  * @param[in,out]  path    The absolute path to the shared resource directory of the application
 305  *                         specified with the @a app_id
 306  * @return  @c 0 on success,
 307  *          otherwise a negative error value
 308  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 309  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 310  * @retval  #APP_MANAGER_ERROR_NO_SUCH_APP        No such application
 311  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 312  */
 313 int app_manager_get_shared_resource_path(const char *app_id, char **path);
 314
 315 /**
 316  * @brief  Gets the absolute path to the shared trusted directory of the application specified
 317  *         with an application ID.
 318  * @details     An application signed with the same certificate can read and write the files of
 319  *              other application's shared trusted directory.
 320  * @since_tizen 2.3
 321  * @remarks     The specified @a path should be released.
 322  *
 323  * @param[in]      app_id  The ID of the application
 324  * @param[in,out]  path    The absolute path to the shared trusted directory of the application
 325  *                         specified with the @a app_id
 326  * @return  @c 0 on success,
 327  *          otherwise a negative error value
 328  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 329  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 330  * @retval  #APP_MANAGER_ERROR_NO_SUCH_APP        No such application
 331  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 332  */
 333 int app_manager_get_shared_trusted_path(const char *app_id, char **path);
 334
 335 /**
 336  * @brief  Gets the absolute path to the shared data directory of the application specified
 337  *         with an application ID.
 338  * @details     An application can only read the files of other application's shared data directory.
 339  * @since_tizen 2.3
 340  * @remarks     The specified @a path should be released.
 341  *
 342  * @param[in]      app_id  The ID of the application
 343  * @param[in,out]  path    The absolute path to the shared data directory of the application
 344  *                         specified with the @a app_id
 345  * @return  @c 0 on success,
 346  *          otherwise a negative error value
 347  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 348  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 349  * @retval  #APP_MANAGER_ERROR_NO_SUCH_APP        No such application
 350  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 351  */
 352 int app_manager_get_external_shared_data_path(const char *app_id, char **path);
 353
 354 /**
 355  * @}
 356  */
 357
 358 #ifdef __cplusplus
 359 }
 360 #endif
 361
 362 #endif /* __TIZEN_APPFW_APP_MANAGER_H */