include/aul.h

   1 /*
   2  *  aul
   3  *
   4  * Copyright (c) 2015 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 #pragma once
  21
  22 #include <errno.h>
  23 #include <bundle.h>
  24 #include <sys/types.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * @brief Return values in AUL.
  32  */
  33 typedef enum _aul_return_val {
  34         AUL_R_EREJECTED = -14,          /**< App disable for mode */
  35         AUL_R_ENOAPP = -13,             /**< Failed to find app ID or pkg ID */
  36         AUL_R_EHIDDENFORGUEST = -11,    /**< App hidden for guest mode */
  37         AUL_R_ENOLAUNCHPAD = -10,       /**< no launchpad */
  38         AUL_R_ETERMINATING = -9,        /**< application terminating */
  39         AUL_R_EILLACC = -8,             /**< Illegal Access */
  40         AUL_R_LOCAL = -7,               /**< Launch by himself */
  41         AUL_R_ETIMEOUT = -6,            /**< Timeout */
  42         AUL_R_ECANCELED = -5,           /**< Operation canceled */
  43         AUL_R_EINVAL = -4,              /**< Invalid argument */
  44         AUL_R_ECOMM = -3,               /**< Comunication Error */
  45         AUL_R_ENOINIT = -2,             /**< AUL handler NOT initialized */
  46         AUL_R_ERROR = -1,               /**< General error */
  47         AUL_R_OK = 0                    /**< General success */
  48 }aul_return_val;
  49
  50 enum app_status {
  51         STATUS_LAUNCHING,
  52         STATUS_CREATED,
  53         STATUS_FOCUS,
  54         STATUS_VISIBLE,
  55         STATUS_BG,
  56         STATUS_DYING,
  57         STATUS_HOME,
  58         STATUS_NORESTART,
  59         STATUS_SERVICE
  60 };
  61
  62 typedef enum _aul_type{
  63         AUL_START,
  64         AUL_RESUME,
  65         AUL_TERMINATE,
  66         AUL_TERMINATE_BGAPP,
  67         AUL_PAUSE,
  68 }aul_type;
  69
  70 /** AUL public key - To check caller's secuirty */
  71 #define AUL_K_CALLER_PID        "__AUL_CALLER_PID__"
  72 /** AUL public key - To check callee's secuirty */
  73 #define AUL_K_CALLEE_PID        "__AUL_CALLEE_PID__"
  74 /** AUL public key - added for multiuser mode */
  75 #define AUL_K_CALLER_UID        "__AUL_CALLER_UID__"
  76 /** AUL public key - added for multiuser mode */
  77 #define AUL_K_CALLEE_UID        "__AUL_CALLEE_UID__"
  78 /** AUL public key - added for multiuser mode */
  79 #define AUL_K_TARGET_UID        "__AUL_TARGET_UID__"
  80 /** AUL public key - To check caller's secuirty */
  81 #define AUL_K_CALLER_APPID      "__AUL_CALLER_APPID__"
  82 /** AUL public key - To check caller's secuirty */
  83 #define AUL_K_CALLEE_APPID      "__AUL_CALLEE_APPID__"
  84 /** AUL public key - To find argv0 */
  85 #define AUL_K_ARGV0             "__AUL_ARGV0__"
  86 /** AUL public key - To measure launching time */
  87 #define AUL_K_STARTTIME         "__AUL_STARTTIME__"
  88 /** AUL public key - To support launching based on mime type */
  89 #define AUL_K_MIME_TYPE         "__AUL_MIME_TYPE__"
  90 /** AUL public key - To support launching based on mime type */
  91 #define AUL_K_UNALIASED_MIME_TYPE               "__AUL_UNALIASED_MIME_TYPE__"
  92 /** AUL public key - To support launching based on mime type */
  93 #define AUL_K_MIME_CONTENT      "__AUL_MIME_CONTENT__"
  94 /** AUL public key - To support launching based on service */
  95 #define AUL_K_SERVICE_NAME              "__AUL_SERVICE_NAME__"
  96 /** AUL public key - To force launch app selector instead of lauchingn default app */
  97 #define AUL_K_FORCE_LAUNCH_APP_SELECTOR "__AUL_FORCE_LAUNCH_APP_SELECTOR__"
  98 /** AUL public key - To support debug argument */
  99 #define AUL_K_DEBUG     "__AUL_DEBUG__"
 100 /** AUL public key - To support SDK */
 101 #define AUL_K_SDK       "__AUL_SDK__"
 102 /** AUL public key - To support Media key */
 103 #define AUL_K_MULTI_KEY "__AUL_MULTI_KEY__"
 104 /** AUL public key - To support Media key */
 105 #define AUL_K_MULTI_KEY_EVENT   "__AUL_MULTI_KEY_EVENT__"
 106 /** AUL public bundle value */
 107 #define AUL_K_PRIVACY_APPID             "__AUL_PRIVACY_APPID__"
 108 /** AUL public bundle value - To support Media key*/
 109 #define AUL_V_KEY_PRESSED       "__AUL_KEY_PRESSED__"
 110 /** AUL public bundle value - To support Media key*/
 111 #define AUL_V_KEY_RELEASED      "__AUL_KEY_RELEASED__"
 112 /** AUL public key - To support rua stat */
 113 #define AUL_SVC_K_RUA_STAT_CALLER "__K_RUA_STAT_CALLER__"
 114 #define AUL_SVC_K_RUA_STAT_TAG    "__K_RUA_STAT_TAG__"
 115 /** AUL public key - To support rua delete */
 116 #define AUL_K_RUA_PKGNAME "__K_RUA_PKGNAME"
 117 /** AUL public key - To support rua delete */
 118 #define AUL_K_RUA_APPPATH "__K_RUA_APPPATH"
 119
 120
 121
 122 /** AUL internal private key */
 123 #define AUL_K_PKG_NAME          "__AUL_PKG_NAME__"
 124 /** AUL internal private key */
 125 #define AUL_K_WAIT_RESULT       "__AUL_WAIT_RESULT__"
 126 /** AUL internal private key */
 127 #define AUL_K_SEND_RESULT       "__AUL_SEND_RESULT__"
 128 /** AUL internal private key */
 129 #define AUL_K_TASK_MANAGE       "__AUL_TASK_MANAGE__"
 130 /** AUL internal private key */
 131 #define AUL_K_APP_TYPE          "__AUL_APP_TYPE__"
 132 /** AUL internal private key - To check original caller's identity */
 133 #define AUL_K_ORG_CALLER_PID    "__AUL_ORG_CALLER_PID__"
 134 /** AUL internal private key - To check forwarded callee app's pid */
 135 #define AUL_K_FWD_CALLEE_PID    "__AUL_FWD_CALLEE_PID__"
 136 /** AUL internal private key */
 137 #define AUL_K_NO_CANCEL        "__AUL_NO_CANCEL__"
 138 /** AUL internal private key */
 139 #define AUL_K_EXEC              "__AUL_EXEC__"
 140 /** AUL internal private key */
 141 #define AUL_K_MULTIPLE          "__AUL_MULTIPLE__"
 142 /** AUL internal private key */
 143 #define AUL_K_PACKAGETYPE       "__AUL_PACKAGETYPE__"
 144 /** AUL internal private key */
 145 #define AUL_K_HWACC             "__AUL_HWACC__"
 146 /** AUL internal private key */
 147 #define AUL_K_APPID             "__AUL_APPID__"
 148 /** AUL internal private key */
 149 #define AUL_K_PID               "__AUL_PID__"
 150 /** AUL internal private key */
 151 #define AUL_K_WID               "__AUL_WID__"
 152 /** AUL internal private key */
 153 #define AUL_K_LEADER_PID        "__AUL_LEADER_PID__"
 154 /** AUL internal private key - To support data control */
 155 #define AUL_K_DATA_CONTROL_TYPE   "__AUL_DATA_CONTROL_TYPE__"
 156 /** AUL internal private key */
 157 #define AUL_K_PKGID             "__AUL_PKGID_"
 158 /** AUL internal private key */
 159 #define AUL_K_INTERNAL_POOL "__AUL_INTERNAL_POOL__"
 160 /** AUL internal private key */
 161 #define AUL_TEP_PATH            "_AUL_TEP_PATH_"
 162 /** AUL internal private key */
 163 #define AUL_K_COMP_TYPE         "__AUL_COMP_TYPE__"
 164 /** AUL internal private key */
 165 #define AUL_K_LOADER_ID         "__AUL_LOADER_ID__"
 166 /** AUL internal private key */
 167 #define AUL_K_LOADER_PATH       "__AUL_LOADER_PATH__"
 168 /** AUL internal private key */
 169 #define AUL_K_WAYLAND_DISPLAY   "__AUL_WAYLAND_DISPLAY__"
 170 /** AUL internal private key */
 171 #define AUL_K_WAYLAND_WORKING_DIR "__AUL_WAYLAND_WORKING_DIR__"
 172
 173 /**
 174  * @brief       This is callback function for aul_launch_init
 175  * @param[in]   type    event's type received from system
 176  * @param[in]   b       In case of RESET events, bundle which is received from peer
 177  * @param[in]   data    user-supplied data
 178  */
 179 typedef int (*aul_handler_fn) (aul_type type, bundle * b, void *data);
 180
 181 /**
 182  * @par Description:
 183  *      This API install your AUL handler and setup AUL internal connection.
 184  * @par Purpose:
 185  *      AUL receive START(RESET), RESUME, TERMINATE events from system.\n
 186  *      This API use to handle the events. \n
 187  * @par Typical use case:
 188  *      In general, you need not use this API.
 189  *      If you use AppCore, you should NOT use this API.
 190  *      AppCore will set default aul_handler.
 191  *
 192  * @param[in]   handler         aul main callback handler function
 193  * @param[in]   data            user-supplied data for start_handler
 194  * @return      0 if success, negative value(<0) if fail\n
 195  * @retval      AUL_R_OK        - success
 196  * @retval      AUL_R_ECANCELD  - aul handler was installed already by others
 197  * @retval      AUL_R_ECOMM     - error to create internal ipc
 198  * @retval      AUL_R_ERROR     - error to attach glib main loop
 199  *
 200  * @warning     If you use AppCore, you should NOT use this API.\n
 201  *              You need glib main loop.\n
 202  * @pre
 203  *      you must have aul handler to use this API.
 204  *      aul_luanch_init register aul handler.
 205  * @code
 206  * #include <aul.h>
 207  * #include <bundle.h>
 208  *
 209  * static int aul_handler(aul_type type, bundle *kb,void *data)
 210  * {
 211  *      switch(type)
 212  *      {
 213  *              case AUL_START:
 214  *                      // process RESET event
 215  *                      break;
 216  *              case AUL_RESUME:
 217  *                      // process RESUME event
 218  *                      break;
 219  *              case AUL_TERMINATE:
 220  *                      // preocess TERMINATE event
 221  *                      break;
 222  *      }
 223  *      return 0;
 224  * }
 225  *
 226  * static GMainLoop *mainloop = NULL;
 227  *
 228  * int main(int argc, char **argv)
 229  * {
 230  *      aul_launch_init(aul_handler,NULL);
 231  *      aul_launch_argv_handler(argc, argv);
 232  *
 233  *      mainloop = g_main_loop_new(NULL, FALSE);
 234  *      g_main_loop_run(mainloop);
 235  * }
 236  *
 237  * @endcode
 238  * @remark
 239  *      This API is only available in User Session.
 240 */
 241 int aul_launch_init(aul_handler_fn handler, void *data);
 242
 243 /**
 244  * @par Description:
 245  *      This API create internal RESET events with given argc, argv \n
 246  * @par Purpose:
 247  *      This API's purpose is to generate reset event.
 248  *      If you want to generate local RESET events with argument vector format, use this API
 249  * @par Typical use case:
 250  *      In general, you need not use this API.
 251  *      AppCore use this API to create internal reset event.
 252  *
 253  * @param[in]   argc    # of args
 254  * @param[in]   argv    list of arg strings
 255  * @return      0 if success, negative value(<0) if fail
 256  * @retval      AUL_R_OK        - success
 257  * @retval      AUL_R_ENOINIT   - aul handler was NOT yet installed
 258  * @retval      AUL_R_ECANCLED  - error to create internal bundle with given argc,argv.
 259  * @retval      AUL_R_ERROR     - general error
 260  *
 261  * @pre
 262  *      you must have aul handler to use this API.
 263  *      aul_luanch_init register aul handler.
 264  * @see
 265  *      aul_launch_init
 266  * @code
 267  * #include <aul.h>
 268  * #include <bundle.h>
 269  *
 270  * int send_local_reset_event()
 271  * {
 272  *      int argc=3;
 273  *      char* argv[4];
 274  *      argv[0] = "local.app";
 275  *      argv[1] = "event_type";
 276  *      argv[2] = "my_reset";
 277  *      argv[3] = NULL;
 278  *      aul_launch_argv_handler(argc,argv);
 279  * }
 280  *
 281  * @endcode
 282  * @remark
 283  *      If you use AppCore, you NEED NOT use this API.
 284  *      This API is only available in User Session.
 285 */
 286 int aul_launch_argv_handler(int argc, char **argv);
 287
 288 /**
 289  * @par Description:
 290  *      This API creates internal RESET events with given bundle \n
 291  * @par Purpose:
 292  *  This API's purpose is to generate reset event.
 293  *  If you want to generate local RESET events with argument vector format, first use
 294  *  bundle_import_from_argv to create a bundle from the argument vector and then use this API
 295  *  Eventually, this API will replace aul_launch_argv_handler().
 296  * @par Typical use case:
 297  *      In general, you need not use this API.
 298  *      AppCore use this API to create internal reset event.
 299  *
 300  * @param[in]   b       bundle
 301  * @return      0 if success, negative value(<0) if fail
 302  * @retval      AUL_R_OK        - success
 303  * @retval      AUL_R_ENOINIT   - aul handler was NOT yet installed
 304  * @retval      AUL_R_ERROR     - general error
 305  *
 306  * @pre
 307  *      you must have aul handler to use this API.
 308  *      aul_luanch_init register aul handler.
 309  * @post
 310  *      None
 311  * @see
 312  *      aul_launch_init, bundle_import_from_argv
 313  * @code
 314  * #include <aul.h>
 315  * #include <bundle.h>
 316  *
 317  * int send_local_reset_event()
 318  * {
 319  *  bundle* b;
 320  *      int argc=3;
 321  *      char* argv[4];
 322  *      argv[0] = "local.app";
 323  *      argv[1] = "event_type";
 324  *      argv[2] = "my_reset";
 325  *      argv[3] = NULL;
 326  *
 327  *      b = bundle_import_from_argv(argc,argv);
 328  *      aul_launch_local(b);
 329  * }
 330  *
 331  * @endcode
 332  * @remark
 333  *      If you use AppCore, you NEED NOT to use this API.
 334  *      This API is only available in User Session.
 335 */
 336 int aul_launch_local(bundle *b);
 337
 338 /**
 339  * @par Description:
 340  *      This API launches application with the given bundle.
 341  *  If the application is not running or a multiple-instance one, this API launches with the given bundle.
 342  *      If the application is running, this API sends a RESET event to the App.
 343  *      While the application is running, if the application cannot receive the RESET event,
 344  *      this API returns a general error(AUL_R_ERROR).\n
 345  * @par Purpose:
 346  *      This API is for caller.
 347  *      This API's purpose is to launch/reset application with given bundle.
 348  * @par Typical use case:
 349  *      If you know the target application's pkgname and bundle types,
 350  *      you can use this API to launch/reset the application.
 351  *
 352  * @param[in]   pkgname         package name to be run as callee
 353  * @param[in]   kb              bundle to be passed to callee
 354  * @return      callee's pid if success, negative value(<0) if fail
 355  * @retval      AUL_R_OK        - success
 356  * @retval      AUL_R_EINVAL    - invaild package name
 357  * @retval      AUL_R_ECOM      - internal AUL IPC error
 358  * @retval      AUL_R_ERROR     - general error
 359  *
 360  * @see
 361  *      aul_open_app
 362  * @code
 363  * #include <aul.h>
 364  * #include <bundle.h>
 365  *
 366  * int launch_inhouse_contact_app()
 367  * {
 368  *      bundle *b;
 369  *      b = bundle_create();
 370  *      bundle_add(b,"type","SIM");
 371  *      aul_launch_app("org.tizen.contact",b);
 372  * }
 373  *
 374  * @endcode
 375  * @remark
 376  *      This API is only available in User Session.
 377  */
 378 int aul_launch_app(const char *appid, bundle *kb);
 379
 380 /**
 381  * @par Description:
 382  *      This API launches application with the given bundle.
 383  *  If the application is not running or a multiple-instance one, this API launches with the given bundle.
 384  *      If the application is running, this API sends a RESET event to the App.
 385  *      While the application is running, if the application cannot receive the RESET event,
 386  *      this API returns a general error(AUL_R_ERROR).\n
 387  * @par Purpose:
 388  *      This API is for caller.
 389  *      This API's purpose is to launch/reset application with given bundle.
 390  * @par Typical use case:
 391  *      If you know the target application's pkgname and bundle types,
 392  *      you can use this API to launch/reset the application.
 393  *
 394  * @param[in]   pkgname         package name to be run as callee
 395  * @param[in]   kb              bundle to be passed to callee
 396  * @param[in]   uid             User ID to launch
 397  * @return      callee's pid if success, negative value(<0) if fail
 398  * @retval      AUL_R_OK        - success
 399  * @retval      AUL_R_EINVAL    - invaild package name
 400  * @retval      AUL_R_ECOM      - internal AUL IPC error
 401  * @retval      AUL_R_ERROR     - general error
 402  *
 403  * @see
 404  *      aul_open_app
 405  * @remark
 406  *      This API is also available in System Session.
 407  */
 408 int aul_launch_app_for_uid(const char *appid, bundle *kb, uid_t uid);
 409
 410 /**
 411  * @par Description:
 412  *  This API launches application, as menu screen launches the app.
 413  *  Thus, if the applocation is running, this API sends a RESUME event to the app.
 414  *  If the application is not running, this API launches the app.
 415  *  While the application is running, if the application cannot receive the RESUME event,
 416  *  AUL tries to raise the application's default window.
 417  *
 418  * @par Purpose:
 419  *      This API is for caller.
 420  *      This API's purpose is to resume/launch application
 421  * @par Typical use case:
 422  *      If you only want to show application with previous state or default state, Use this API.
 423  *
 424  * @param[in]   pkgname         package name to be resume as callee
 425  * @return      callee's pid if success, negative value(<0) if fail
 426  * @retval      AUL_R_OK        - success
 427  * @retval      AUL_R_EINVAL    - invaild package name
 428  * @retval      AUL_R_ECOM      - internal AUL IPC error
 429  * @retval      AUL_R_ERROR     - general error
 430  *
 431  * @see
 432  *      aul_launch_app, aul_app_is_running, aul_resume_pid
 433  * @code
 434  * #include <aul.h>
 435  * #include <bundle.h>
 436  *
 437  * int open_inhouse_contact_app()
 438  * {
 439  *      if(aul_app_is_running("org.tizen.contact"))
 440  *              aul_open_app("org.tizen.contact");
 441  * }
 442  *
 443  * @endcode
 444  * @remark
 445  *      If you don't want to launch the app,
 446  *      you should check app's running state with aul_app_is_running.
 447  *      This API will launch the application if the application is not running.
 448  *      This API is only available in User Session.
 449 */
 450 int aul_open_app(const char *appid);
 451
 452 /**
 453  * @par Description:
 454  *      This API trigger to resume application
 455  *      If the application is running, this API send a resume event to the App.
 456  *      If the application is not running, this API returns fail.
 457  *      Although the application is running, if the application cannot receive resume event,
 458  *      AUL try to raise the application's default windows.
 459  * @par Purpose:
 460  *      This API is for caller.
 461  *      This API's purpose is to send resume event.
 462  * @par Typical use case:
 463  *      If you only want to show application with previous state or default state, Use this API.
 464  *
 465  * @param[in]   pkgname         package name to be resume as callee
 466  * @return      callee's pid if success, negative value(<0) if fail
 467  * @retval      AUL_R_OK        - success
 468  * @retval      AUL_R_EINVAL    - invaild package name
 469  * @retval      AUL_R_ECOM      - internal AUL IPC error
 470  * @retval      AUL_R_ERROR     - general error
 471  *
 472  * @see
 473  *      aul_launch_app, aul_app_is_running, aul_resume_pid
 474  * @deprecated
 475  *  This function will be deprecated. Use aul_open_add() instead.
 476  * @code
 477  * #include <aul.h>
 478  * #include <bundle.h>
 479  *
 480  * int resume_inhouse_contact_app()
 481  * {
 482  *      if(aul_app_is_running("org.tizen.contact"))
 483  *              aul_resume_app("org.tizen.contact");
 484  * }
 485  *
 486  * @endcode
 487  * @remark
 488  *      If you don't want to launch the app,
 489  *      you should check app's running state with aul_app_is_running.
 490  *      This API will launch the application if the application is not running.
 491  *      If you want to only resume without launching in multiple instance application model,
 492  *      you should use aul_resume_pid.
 493  *      This API is only available in User Session.
 494 */
 495 int aul_resume_app(const char *appid);
 496
 497 /**
 498  * @par Description:
 499  *      This API trigger to resume application
 500  *      If the application is running, this API send a resume event to the App.
 501  *      If the application is not running, this API return AUL_R_ERROR.
 502  *      Although the application is running, if the application cannot receive resume event,
 503  *      AUL try to raise the application's default windows.
 504  * @par Purpose:
 505  *      This API is for caller.
 506  *      This API's purpose is to send resume event.
 507  * @par Typical use case:
 508  *      In multiple application model, If you want to only resume specific application, Use this API
 509  *
 510  * @param[in]   pid     application's pid to be resumed
 511  * @return      0 if success, negative value(<0) if fail
 512  * @retval      AUL_R_OK        - success
 513  * @retval      AUL_R_EINVAL    - invaild pid
 514  * @retval      AUL_R_ECOM      - internal AUL IPC error
 515  * @retval      AUL_R_ERROR     - general error (include application is not running)
 516  * @warning     This API need to require root or inhouse permisssion \n
 517  *              If you have not the permission, this API return AUL_R_ERROR. \n
 518  * @see
 519  *      aul_launch_app
 520  * @code
 521  * #include <aul.h>
 522  * #include <bundle.h>
 523  *
 524  * int iterfunc(const aul_app_info *info, void *data)
 525  * {
 526  *      if(strcmp(info->pkg_name,"org.tizen.contact")==0)
 527  *              aul_resume_pid(info->pid);
 528  * }
 529  *
 530  * int iterate_running_apps()
 531  * {
 532  *      return aul_app_get_running_app_info(iterfunc,NULL);
 533  * }
 534  *
 535  * @endcode
 536  * @remark
 537  *      This API is only available in User Session.
 538 */
 539 int aul_resume_pid(int pid);
 540
 541 /**
 542  * @par Description:
 543  *      This API trigger to terminate application
 544  *
 545  *      If the application is running, this API send a terminate event to the App. \n
 546  *      If the app cannot receive the event, AUL kill forcely the application.\n
 547  * @par Purpose:
 548  *      This API's purpose is to kill application
 549  * @par Typical use case:
 550  *      In general, Application like Task Manager use this API.
 551  *
 552  *              This API need to require root or inhouse permisssion. \n
 553  *
 554  * @param[in]   pid     application's pid to be terminated
 555  * @return      0 if success, negative value(<0) if fail
 556  * @retval      AUL_R_OK        - success
 557  * @retval      AUL_R_EINVAL    - invaild pid
 558  * @retval      AUL_R_ECOM      - internal AUL IPC error
 559  * @retval      AUL_R_ERROR     - general error
 560  * @warning     This API need to require root or inhouse permisssion. \n
 561  *
 562  * @code
 563  * #include <aul.h>
 564  * #include <bundle.h>
 565  *
 566  * int iterfunc(const aul_app_info *info, void *data)
 567  * {
 568  *      if(strcmp(info->pkg_name,"org.tizen.contact")==0)
 569  *              aul_terminate_pid(info->pid);
 570  * }
 571  *
 572  * int iterate_running_apps()
 573  * {
 574  *      return aul_app_get_running_app_info(iterfunc,NULL);
 575  * }
 576  *
 577  * @endcode
 578  * @remark
 579  *      If you have not the permission, this API return AUL_R_ERROR. \n
 580  *      This API is only available in User Session.
 581 */
 582 int aul_terminate_pid(int pid);
 583
 584 /**
 585  * @par Description:
 586  *      This API trigger to terminate application asynchronously
 587  *
 588  *      If the application is running, this API send a terminate event to the App. \n
 589  *      If the app cannot receive the event, AUL kill forcely the application.\n
 590  * @par Purpose:
 591  *      This API's purpose is to kill application
 592  * @par Typical use case:
 593  *      In general, Application like Task Manager use this API.
 594  *
 595  *              This API need to require root or inhouse permisssion. \n
 596  *
 597  * @param[in]   pid     application's pid to be terminated
 598  * @return      0 if success, negative value(<0) if fail
 599  * @retval      AUL_R_OK        - success
 600  * @retval      AUL_R_EINVAL    - invaild pid
 601  * @retval      AUL_R_ECOM      - internal AUL IPC error
 602  * @retval      AUL_R_ERROR     - general error
 603  * @warning     This API need to require root or inhouse permisssion. \n
 604  * @remark
 605  *      If you have not the permission, this API return AUL_R_ERROR. \n
 606  *      This API is only available in User Session.
 607 */
 608 int aul_terminate_pid_async(int pid);
 609
 610 /**
 611  *@brief Running application's information structure retrieved by AUL
 612  */
 613 typedef struct _aul_app_info {
 614         int pid;                /**< app's pid if running*/
 615         char* pkg_name;         /**< application id */
 616         char* app_path;         /**< application excutable path */
 617         char* appid;
 618 } aul_app_info;
 619
 620 /**
 621  * @brief iterator function running with aul_app_get_running_app_info
 622  * @param[out]  ainfo   aul_app_info retreived by aul_app_get_running_app_info
 623  * @param[out]  data    user-supplied data
 624 */
 625 typedef int (*aul_app_info_iter_fn)(const aul_app_info *ainfo, void *data);
 626
 627 /**
 628  * @par Description:
 629  *      This API ask a application is running by application package name.
 630  * @par Purpose:
 631  *      To know whether some application is running or not, use this API
 632  * @par Typical use case:
 633  *      For example, If you want to know browser application running,
 634  *      you can check it by using this API.
 635  *
 636  * @param[in]   pkgname application package name
 637  * @return      true / false
 638  * @retval      1       app_name is running now.
 639  * @retval      0       app_name is NOT running now.
 640  *
 641  * @code
 642  * #include <aul.h>
 643  *
 644  * int is_running_browser_app()
 645  * {
 646  *      return aul_app_is_running("org.tizen.browser");
 647  * }
 648  *
 649  * @endcode
 650  * @remark
 651  *      This API is only available in User Session.
 652  *
 653  */
 654 int aul_app_is_running(const char *appid);
 655
 656 /**
 657  * @par Description:
 658  *      This API ask a application is running by application package name.
 659  * @par Purpose:
 660  *      To know whether some application is running or not, use this API
 661  * @par Typical use case:
 662  *      For example, If you want to know browser application running,
 663  *      you can check it by using this API.
 664  *
 665  * @param[in]   pkgname application package name
 666  * @param[in]   uid     User ID
 667  * @return      true / false
 668  * @retval      1       app_name is running now.
 669  * @retval      0       app_name is NOT running now.
 670  *
 671  * @endcode
 672  * @remark
 673  *      This API is only available in System Session.
 674  */
 675 int aul_app_is_running_for_uid(const char *appid, uid_t uid);
 676
 677 /**
 678  * @par Description:
 679  *      This API use to get running application list.
 680  *      This API call iter_fn with each aul_app_info of running apps when running application is found.
 681  * @par Purpose:
 682  *      If you want to get running application list, use this API
 683  *      This API give you running applications which has SLP desktop file.
 684  * @par Typical use case:
 685  *      In general, this API is used by task manager appllication. (running application list viewer)
 686  *
 687  * @param[in]   iter_fn         iterator function
 688  * @param[in]   data            user-supplied data for iter_fn
 689  * @return      0 if success, negative value(<0) if fail
 690  * @retval      AUL_R_OK        - success
 691  * @retval      AUL_R_ERROR     - internal error
 692  *
 693  * @code
 694  * #include <aul.h>
 695  *
 696  * int iterfunc(const aul_app_info* info, void* data)
 697  * {
 698  *      printf("\t==========================\n");
 699  *      printf("\t pkg_name: %s\n", info->appid);
 700  *      printf("\t app_path: %s\n", info->app_path);
 701  *      printf("\t running pid: %d\n", info->pid);
 702  *      printf("\t==========================\n");
 703  *      return 0;
 704  * }
 705  *
 706  * int iterate_running_apps()
 707  * {
 708  *      return aul_app_get_running_app_info(iterfunc,NULL);
 709  * }
 710  *
 711  * @endcode
 712  * @remark
 713  *      This API should use if you want to know running application which has desktop files.
 714  *      If you want to get all process list, you must iterate process information by using proc filesystem
 715  *      Or, If you want to get all window list, you must iterate XWindows by using XWindow APIs
 716  *      This API is only available in User Session.
 717  */
 718 int aul_app_get_running_app_info(aul_app_info_iter_fn iter_fn, void *data);
 719
 720 /**
 721  * @par Description:
 722  *      This API get application package name by pid
 723  * @par Purpose:
 724  *      If you want to get package name of running application, use this API
 725  * @par Typical use case:
 726  *      In general, You can use this API when you want to know caller's information.
 727  *
 728  * @param[in]   pid             given pid
 729  * @param[out]  pkgname         pkgname to be get
 730  * @param[in]   len             length of pkgname
 731  * @return      0 if success, negative value(<0) if fail
 732  * @retval      AUL_R_OK        - success
 733  * @retval      AUL_R_ERROR     - no such a package name
 734  * @code
 735  * #include <aul.h>
 736  * #include <bundle.h>
 737  *
 738  * static int app_reset(bundle *b, void *data)
 739  * {
 740  *      int pid;
 741  *      char appname[255];
 742  *
 743  *      pid = atoi(bundle_get_val(b,AUL_K_CALLER_PID));
 744  *      aul_app_get_pkgname_bypid(pid, appname, sizeof(appname));
 745  * }
 746  *
 747  * @endcode
 748  * @remark
 749  *      This API is only available in User Session.
 750 */
 751 int aul_app_get_pkgname_bypid(int pid, char *pkgname, int len);
 752
 753 /**
 754  * @par Description:
 755  *      This API get application pkgid by pid
 756  * @par Purpose:
 757  *      If you want to get pkgid of running application, use this API
 758  * @par Typical use case:
 759  *      In general, You can use this API when you want to know caller's information.
 760  *
 761  * @param[in]   pid             given pid
 762  * @param[out]  pkgid           package id
 763  * @param[in]   len             length of pkgid
 764  * @return      0 if success, negative value(<0) if fail
 765  * @retval      AUL_R_OK        - success
 766  * @retval      AUL_R_ERROR     - no such a appid
 767  *
 768  * @code
 769  * #include <aul.h>
 770  * #include <bundle.h>
 771  *
 772  * static int app_reset(bundle *b, void *data)
 773  * {
 774  *      int pid;
 775  *      char pkgid[255];
 776  *
 777  *      pid = atoi(bundle_get_val(b, AUL_K_CALLER_PID));
 778  *      aul_app_get_pkgid_bypid(pid, pkgid, sizeof(pkgid));
 779  * }
 780  *
 781  * @endcode
 782  * @remark
 783  *      This API is only available in User Session.
 784 */
 785 int aul_app_get_pkgid_bypid(int pid, char *pkgid, int len);
 786
 787 /**
 788  * @par Description:
 789  *      This API get application pkgid by pid
 790  * @par Purpose:
 791  *      If you want to get pkgid of running application, use this API
 792  * @par Typical use case:
 793  *      In general, You can use this API when you want to know caller's information.
 794  *
 795  * @param[in]   pid             given pid
 796  * @param[out]  pkgid           package id
 797  * @param[in]   len             length of pkgid
 798  * @param[in]   uid             User ID
 799  * @return      0 if success, negative value(<0) if fail
 800  * @retval      AUL_R_OK        - success
 801  * @retval      AUL_R_ERROR     - no such a appid
 802  *
 803  * @remark
 804  *      This API is also available in System Session.
 805 */
 806 int aul_app_get_pkgid_bypid_for_uid(int pid, char *pkgid, int len, uid_t uid);
 807
 808 /**
 809  * @par Description:
 810  *      This API get application appid by pid
 811  * @par Purpose:
 812  *      If you want to get appid of running application, use this API
 813  * @par Typical use case:
 814  *      In general, You can use this API when you want to know caller's information.
 815  *
 816  * @param[in]   pid             given pid
 817  * @param[out]  appid           application id
 818  * @param[in]   len             length of pkgname
 819  * @return      0 if success, negative value(<0) if fail
 820  * @retval      AUL_R_OK        - success
 821  * @retval      AUL_R_ERROR     - no such a appid
 822  * @code
 823  * #include <aul.h>
 824  * #include <bundle.h>
 825  *
 826  * static int app_reset(bundle *b, void *data)
 827  * {
 828  *      int pid;
 829  *      char appid[255];
 830  *
 831  *      pid = atoi(bundle_get_val(b,AUL_K_CALLER_PID));
 832  *      aul_app_get_appid_bypid(pid, appid, sizeof(appid));
 833  * }
 834  *
 835  * @endcode
 836  * @remark
 837  *      This API is only available in User Session.
 838 */
 839 int aul_app_get_appid_bypid(int pid, char *appid, int len);
 840
 841 /**
 842  * @par Description:
 843  *      This API get application appid by pid
 844  * @par Purpose:
 845  *      If you want to get appid of running application, use this API
 846  * @par Typical use case:
 847  *      In general, You can use this API when you want to know caller's information.
 848  *
 849  * @param[in]   pid             given pid
 850  * @param[out]  appid           application id
 851  * @param[in]   len             length of pkgname
 852  * @param[in]   uid             User ID
 853  * @return      0 if success, negative value(<0) if fail
 854  * @retval      AUL_R_OK        - success
 855  * @retval      AUL_R_ERROR     - no such a appid
 856  * @remark
 857  *      This API is also available in System Session.
 858 */
 859 int aul_app_get_appid_bypid_for_uid(int pid, char *appid, int len, uid_t uid);
 860
 861 /**
 862  * @par Description:
 863  *      This API launch application associated with given filename
 864  * @par Purpose:
 865  *      This API is for caller.
 866  *      This API launch application based on mime type.
 867  *      This API find mime_type associated with file name,
 868  *      and then find default app associated with found mime_type
 869  *      and then launch the app with filename argument.
 870  * @par Typical use case:
 871  *      You can launch application to process given filename.
 872  *      That is, Even if you don't know the specific application's pkgname,
 873  *      you can launch the applicaiton processing given filename .
 874  *      For example, If you want to process image file, you can simply launch image viewer.
 875  *      At that time, you can use this APIs like aul_open_file("myimage.jpg");
 876  *
 877  * @param[in]   filename        filename
 878  * @return      callee's pid or 0 if success, negative value if fail\n
 879  *              (when no found default app, return 0)
 880  * @retval      AUL_R_OK        - success
 881  * @retval      AUL_R_EINVAL    - invalid argument(filename)
 882  * @retval      AUL_R_ECOM      - internal AUL IPC error
 883  * @retval      AUL_R_ERROR     - general error
 884  *
 885  * @code
 886  * #include <aul.h>
 887  *
 888  * int view_image_file(char *filename)
 889  * {
 890  *      aul_open_file(filename);
 891  * }
 892  *
 893  * @endcode
 894  * @remark
 895  *      This API is only available in User Session.
 896  *
 897  */
 898 int aul_open_file(const char* filename);
 899
 900 /**
 901  * @par Description:
 902  *      This API launch application associated with given specific mimetype
 903  * @par Purpose:
 904  *      This API is for caller.
 905  *      This API launch application based on mime type like aul_open_file API.
 906  *      But, This API don't find mime_type associated with file name.
 907  *      This API use mimetype given by user. By using given mimetype, find default application.
 908  *      and then launch the app with filename argument.
 909  * @par Typical use case:
 910  *      Some files cannot extract exact mimetype automatically.
 911  *      For example, To know mime type of files with DRM lock, first we should unlock DRM file.
 912  *      In this case, You can use this API.
 913  *      First, unlock DRM file, and extract mimetype from unlock file by using aul_get_mime_from_file,
 914  *      and then, use this API with DRM file and extracted mime type.
 915  *
 916  * @param[in]   filename        filename
 917  * @param[in]   mimetype        specific mimetype
 918  * @return      callee's pid or 0 if success, negative value if fail\n
 919  *              (when no found default app, return 0)
 920  * @retval      AUL_R_OK        - success
 921  * @retval      AUL_R_EINVAL    - invalid argument(filename,mimetype)
 922  * @retval      AUL_R_ECOM      - internal AUL IPC error
 923  * @retval      AUL_R_ERROR     - general error
 924  *
 925  * @see
 926  *      aul_open_file, aul_get_mime_from_file
 927  * @code
 928  * #include <aul.h>
 929  *
 930  * int view_drm_image_file(char *drm_filename)
 931  * {
 932  *      char* mimetype;
 933  *      // you must implement this function
 934  *      mimetype = get_mimetype_from_drmfile(drm_filename);
 935  *
 936  *      aul_open_file_with_mimetype(drm_filename,mimetype);
 937  * }
 938  *
 939  * @endcode
 940  * @remark
 941  *      This API is only available in User Session.
 942  */
 943 int aul_open_file_with_mimetype(const char *filename, const char *mimetype);
 944
 945 /**
 946  * @par Description:
 947  *      This API launch application associated with content like "http://www.samsung.com"
 948  * @par Purpose:
 949  *      This API is for caller.
 950  *      This API launch application based on mime type.
 951  *      This API find mime_type associated with content,
 952  *      and then find default app associated with found mime_type,
 953  *      and then launch the app with content argument.
 954  * @par Typical use case:
 955  *      You can launch application to process given content.
 956  *      That is, Even if you don't know the specific application's pkgname,
 957  *      you can launch the applicaiton processing given content.
 958  *      For example, If you want to process URL "http://www.samsung.com",
 959  *      you can simply launch browser.
 960  *      At that time, you can use this APIs like aul_open_content("http://www.samsung.com");
 961  *
 962  * @param[in]   content         content
 963  * @return      callee's pid or 0 if success, negative value if fail\n
 964  *              (when no found default app, return 0)
 965  * @retval      AUL_R_OK        - success
 966  * @retval      AUL_R_EINVAL    - invalid argument(content)
 967  * @retval      AUL_R_ECOM      - internal AUL IPC error
 968  * @retval      AUL_R_ERROR     - general error or no found mimetype
 969  *
 970  * @code
 971  * #include <aul.h>
 972  *
 973  * int view_url(char *url)
 974  * {
 975  *      aul_open_content(url);
 976  * }
 977  *
 978  * @endcode
 979  * @remark
 980  *      This API is only available in User Session.
 981  *
 982  */
 983 int aul_open_content(const char* content);
 984
 985 /**
 986  * @par Description:
 987  *       This API get the default application(appid) associated with MIME type
 988  * @par Purpose:
 989  *      This API use to get default application associteted with mimetype
 990  *      In general, Setting Application need this API.
 991  * @par Typical use case:
 992  *      Setting Application show mapping of default application / mimetype
 993  *
 994  * @param[in]   mimetype        a mime type
 995  * @param[out]  defapp          a application appid of the app
 996  * @param[in]   len             length of defapp
 997  * @return      0 if success, negative value if fail
 998  * @retval      AUL_R_OK        - success
 999  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
1000  * @retval      AUL_R_ERROR     - general error or no found mimetype
1001  *
1002  * @see
1003  *      aul_set_defapp_with_mime
1004  * @code
1005  * #include <aul.h>
1006  *
1007  * void get_text_html_defapp()
1008  * {
1009  *      char appname[255];
1010  *      aul_get_defapp_from_mime("text/html",appname,sizeof(appname));
1011  * }
1012  *
1013  * @endcode
1014  * @remark
1015  *      This API is only available in User Session.
1016  *
1017  */
1018 int aul_get_defapp_from_mime(const char *mimetype, char *defapp, int len);
1019
1020 /**
1021  * @par Description:
1022  *       This API set the default application(appid) associated with MIME type
1023  * @par Purpose:
1024  *      This API use to change default application associteted with mimetype
1025  *      In general, Setting Application or Installer need this API.
1026  * @par Typical use case:
1027  *      Default Application associated with mimetype can be changed by Setting Application or installer
1028  *      So, application to process specific mimetype can be substituted.
1029  *
1030  * @param[in]   mimetype        a mime type
1031  * @param[in]   defapp          a application appid of the app to be set
1032  * @return      0 if success, negative value if fail
1033  * @retval      AUL_R_OK        - success
1034  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
1035  * @retval      AUL_R_ERROR     - general error
1036  *
1037  * @see
1038  *      aul_get_defapp_from_mime
1039  * @code
1040  * #include <aul.h>
1041  *
1042  * void set_text_html_defapp()
1043  * {
1044  *      aul_set_defapp_with_mime("text/html","org.tizen.browser");
1045  * }
1046  *
1047  * @endcode
1048  * @remark
1049  *      This API is only available in User Session.
1050 */
1051 int aul_set_defapp_with_mime(const char *mimetype, const char *defapp);
1052
1053 /**
1054  * @par Description:
1055  *      This API get the mimetype associated with filename
1056  * @par Purpose:
1057  *      This API use to get mimetype associteted with given filename
1058  *      In general, This API use when you want to know only mimetype given filename.
1059  * @par Typical use case:
1060  *      For example, In trasfering data through bluetooth,
1061  *      additional information like mimetype should be added.
1062  *      In such situation, You can get mimetype by using this API.
1063  *
1064  * @param[in]   filename        file name
1065  * @param[out]  mimetype        a mime type
1066  * @param[in]   len             length of mimetype
1067  * @return      0 if success, negative value if fail
1068  * @retval      AUL_R_OK        - success
1069  * @retval      AUL_R_EINVAL    - invalid argument(filename)
1070  * @retval      AUL_R_ERROR     - general error
1071  *
1072  * @code
1073  * #include <aul.h>
1074  *
1075  * void get_mimetype()
1076  * {
1077  *      char mimetype[255];
1078  *      aul_get_mime_from_file("image.jpg",mimetype,sizeof(mimetype));
1079  * }
1080  *
1081  * @endcode
1082  * @remark
1083  *      This API is only available in User Session.
1084  */
1085 int aul_get_mime_from_file(const char *filename, char *mimetype, int len);
1086
1087 /**
1088  * @par Description:
1089  *      This API get the mimetype associated with given content
1090  * @par Purpose:
1091  *      This API use to get mimetype associteted with given content
1092  *      In general, This API use when you want to know only mimetype given content
1093  * @par Typical use case:
1094  *      For example, In trasfering data through bluetooth,
1095  *      additional information like mimetype should be added.
1096  *      In such situation, You can get mimetype by using this API.
1097  *
1098  * @param[in]   content         content string like "011-0000-0000"
1099  * @param[out]  mimetype        a mime type
1100  * @param[in]   len             length of mimetype
1101  * @return      0 if success, negative value if fail
1102  * @retval      AUL_R_OK        - success
1103  * @retval      AUL_R_EINVAL    - invalid argument(content)
1104  * @retval      AUL_R_ERROR     - general error
1105  *
1106  * @code
1107  * #include <aul.h>
1108  *
1109  * void get_mimetype()
1110  * {
1111  *      char mimetype[255];
1112  *      aul_get_mime_from_content("http://www.samsung.com",mimetype,sizeof(mimetype));
1113  * }
1114  *
1115  * @endcode
1116  * @remark
1117  *      This API is only available in User Session.
1118 */
1119 int aul_get_mime_from_content(const char *content, char *mimetype, int len);
1120
1121 /**
1122  * @par Description:
1123  *      This API get the icon's name associated with given mimetype
1124  * @par Purpose:
1125  *      This API use to get icon's name associteted with given mimetype
1126  * @par Typical use case:
1127  *      If you want to show mimetype's icon, use this API.
1128  *
1129  * @param[in]   mimetype        a mime type
1130  * @param[out]  iconname        icon's name
1131  * @param[in]   len             length of iconname
1132  * @return      0 if success, negative value if fail
1133  * @retval      AUL_R_OK        - success
1134  * @retval      AUL_R_EINVAL    - invalid argument(content)
1135  * @retval      AUL_R_ERROR     - general error (no such mime type)
1136  *
1137  * @code
1138  * #include <aul.h>
1139  *
1140  * void get_mime_icon()
1141  * {
1142  *      char icon[255];
1143  *      aul_get_mime_icon("text/html",icon,sizeof(icon));
1144  * }
1145  *
1146  * @endcode
1147  * @remark
1148  *      This API is only available in User Session.
1149  */
1150 int aul_get_mime_icon(const char *mimetype, char *iconname, int len);
1151
1152 /**
1153  * @par Description:
1154  *      This API get the extensions associated with given mimetype
1155  * @par Purpose:
1156  *      This API use to get extensions associteted with given mimetype
1157  * @par Typical use case:
1158  *      In general, user is not familiar with mimetype(text/html),
1159  *      user is familiar with extenstions(*.html, *.htm)
1160  *      So, To show mimetype information to user, use this API
1161  *
1162  * @param[in]   mimetype        a mime type
1163  * @param[out]  extlist         extentions (ex> mpeg,mpg,mpe)
1164  * @param[in]   len             length of extlist
1165  * @return      0 if success, negative value if fail
1166  * @retval      AUL_R_OK        - success
1167  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
1168  * @retval      AUL_R_ERROR     - general error (no mimetype or no extenstion)
1169  *
1170  * @see
1171  *      aul_get_mime_description
1172  * @code
1173  * #include <aul.h>
1174  *
1175  * void get_extension()
1176  * {
1177  *      char extlist[255];
1178  *      aul_get_mime_extension("text/html",extlist,sizeof(extlist));
1179  * }
1180  *
1181  * @endcode
1182  * @remark
1183  *      Some mimetype don't have extension.
1184  *      In that case, You can use aul_get_mime_description.
1185  *      This API is only available in User Session.
1186 */
1187 int aul_get_mime_extension(const char *mimetype, char *extlist, int len);
1188
1189 /**
1190  * @par Description:
1191  *      This API get the description associated with given mimetype
1192  * @par Purpose:
1193  *      This API use to get description associteted with given mimetype
1194  * @par Typical use case:
1195  *      In general, user is not familiar with mimetype(text/html),
1196  *      user is familiar with well-knowing information like extenstions(*.html, *.htm)
1197  *      But, some mimetype don't have extenstion.
1198  *      At that time,to show mimetype information to user, use this API
1199  *
1200  * @param[in]   mimetype        a mime type
1201  * @param[out]  desc            description (ex> Call client)
1202  * @param[in]   len             length of desc
1203  * @return      0 if success, negative value if fail
1204  * @retval      AUL_R_OK        - success
1205  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
1206  * @retval      AUL_R_ERROR     - general error (no mimetype or no descrition)
1207  *
1208  * @see
1209  *      aul_get_mime_extension
1210  * @code
1211  * #include <aul.h>
1212  *
1213  * void get_information_from_mime()
1214  * {
1215  *      char info[255];
1216  *      if(aul_get_mime_extension("text/html",info,sizeof(info))<0){
1217  *              aul_get_mime_description("text/html",info,sizeof(info));
1218  *      }
1219  * }
1220  *
1221  * @endcode
1222  * @remark
1223  *      This API is only available in User Session.
1224  */
1225 int aul_get_mime_description(const char *mimetype, char *desc, int len);
1226
1227 /**
1228  * @par Description:
1229  *      This API create service result bundle based on bundle received in reset event.
1230  * @par Purpose:
1231  *      This API use to create result bundle to send it to caller.
1232  * @par Typical use case:
1233  *      This API is for callee which provide application service.\n
1234  *      To send result to caller, You must create result bundle. \n
1235  *      Callee(application providing the service) can send result by using this API and aul_send_service_result.
1236  *
1237  * @param[in]   inb             bundle received in reset event
1238  * @param[out]  outb            bundle to use for returning result
1239  * @return      0 if success, negative value(<0) if fail
1240  * @retval      AUL_R_OK        - success
1241  * @retval      AUL_R_EINVAL    - inb is not bundle created by aul_open_service
1242  * @retval      AUL_R_ERROR     - general error
1243  *
1244  * @pre
1245  *      To create result bundle, You need received original bundle.
1246  *      The original bundle can get from app_reset handler.
1247  * @post
1248  *      None
1249  * @see
1250  *      aul_send_service_result
1251  * @code
1252  * #include <aul.h>
1253  * #include <bundle.h>
1254  *
1255  * int app_reset(bundle *b, void *data)
1256  * {
1257  *      ad->recved_bundle = bundle_dup(b);
1258  * }
1259  *
1260  * int click_ok()
1261  * {
1262  *      bundle* res_bundle;
1263  *      aul_create_result_bundle(ad->recved_bundle,&res_bundle);
1264  *      bundle_add(res_bundle, "result", "1");
1265  *      aul_send_service_result(res_bundle);
1266  * }
1267  * @endcode
1268  * @remark
1269  *      This API is only available in User Session.
1270  *
1271  */
1272 int aul_create_result_bundle(bundle *inb, bundle **outb);
1273
1274 /**
1275  * @par Description:
1276  *      This API send service result to caller with bundle
1277  * @par Purpose:
1278  *      This API is used to send result bundle to caller.
1279  * @par Typical use case:
1280  *      This API is for callee which provide application service.\n
1281  *      To send result to caller, You can use this API after creating result bundle. \n
1282  *      Callee(application to provide service) can send result by using this API and aul_create_result_bundle.
1283  *
1284  * @param[in]   b      Result data in bundle format
1285  * @return      0 if success, negative value(<0) if fail
1286  * @retval      AUL_R_OK        - success
1287  * @retval      AUL_R_EINVAL    - invalid result bundle
1288  * @retval      AUL_R_ECOMM     - internal AUL IPC error
1289  * @retval      AUL_R_ERROR     - general error
1290  *
1291  * @pre
1292  *      To send result bundle, You must create result bundle.
1293  *      see aul_create_result_bundle
1294  * @post
1295  *      None
1296  * @see
1297  *      aul_create_result_bundle
1298  * @code
1299  * #include <aul.h>
1300  * #include <bundle.h>
1301  *
1302  * int app_reset(bundle *b, void *data)
1303  * {
1304  *      ad->recved_bundle = bundle_dup(b);
1305  * }
1306  *
1307  * int click_ok()
1308  * {
1309  *      bundle* res_bundle;
1310  *      aul_create_result_bundle(ad->recved_bundle,&res_bundle);
1311  *      bundle_add(res_bundle, "result", "1");
1312  *      aul_send_service_result(res_bundle);
1313  * }
1314  * @endcode
1315  * @remark
1316  *      This API is only available in User Session.
1317  *
1318  */
1319 int aul_send_service_result(bundle *b);
1320
1321 /**
1322  * @par Description:
1323  *      This API sets callback fuction that will be called when applications die.
1324  * @par Purpose:
1325  *      This API's purpose is to listen the application dead event.
1326  *      In general, task manager Application need this API.
1327  *
1328  * @param[in]   func            callback function
1329  * @param[in]   data            user data
1330  * @return      0 if success, negative value if fail
1331  * @retval      AUL_R_OK        - success
1332  * @retval      AUL_R_ERROR     - general error
1333  *
1334  * @see
1335  *      aul_listen_app_launch_signal
1336  * @code
1337  * #include <aul.h>
1338  *
1339  * int app_dead_handler(int pid, void *data)
1340  * {
1341  *      printf("===> %s : %d\n", __FUNCTION__, pid);
1342  *      return 0;
1343  * }
1344  *
1345  * void dead_listen()
1346  * {
1347  *      aul_listen_app_dead_signal(app_dead_handler, NULL);
1348  * }
1349  *
1350  * @endcode
1351  * @remark
1352  *      This API is only available in User Session.
1353  *
1354  */
1355 int aul_listen_app_dead_signal(int (*func) (int, void *), void *data);
1356
1357 /**
1358  * @par Description:
1359  *      This API sets callback fuction that will be called when applications are launched.
1360  * @par Purpose:
1361  *      This API's purpose is to listen the application launching event.
1362  *      In general, task manager Application need this API.
1363  *
1364  * @param[in]   func            callback function
1365  * @param[in]   data            user data
1366  * @return      0 if success, negative value if fail
1367  * @retval      AUL_R_OK        - success
1368  * @retval      AUL_R_ERROR     - general error
1369  *
1370  * @see
1371  *      aul_listen_app_dead_signal
1372  * @code
1373  * #include <aul.h>
1374  *
1375  * int app_launch_handler(int pid, void *data)
1376  * {
1377  *      printf("===> %s : %d\n", __FUNCTION__, pid);
1378  *      return 0;
1379  * }
1380  *
1381  * void dead_listen()
1382  * {
1383  *      aul_listen_app_launch_signal(app_launch_handler, NULL);
1384  * }
1385  *
1386  * @endcode
1387  * @remark
1388  *      This API is only available in User Session.
1389  *
1390  */
1391 int aul_listen_app_launch_signal(int (*func) (int, void *), void *data);
1392
1393 /**
1394  * @par Description:
1395  *      This API sets callback fuction that will be called when applications are launched.
1396  * @par Purpose:
1397  *      This API's purpose is to listen the application launching event.
1398  *      In general, task manager Application need this API.
1399  *
1400  * @param[in]   func            callback function
1401  * @param[in]   data            user data
1402  * @return      0 if success, negative value if fail
1403  * @retval      AUL_R_OK        - success
1404  * @retval      AUL_R_ERROR     - general error
1405  *
1406  * @see
1407  *      aul_listen_app_dead_signal
1408  * @code
1409  * #include <aul.h>
1410  *
1411  * int app_launch_handler(int pid, const char *app_id, void *data)
1412  * {
1413  *      printf("===> %s : %d, %s\n", __FUNCTION__, pid, app_id);
1414  *      return 0;
1415  * }
1416  *
1417  * void dead_listen()
1418  * {
1419  *      aul_listen_app_launch_signal(app_launch_handler, NULL);
1420  * }
1421  *
1422  * @endcode
1423  * @remark
1424  *      This API is only available in User Session.
1425  *
1426  */
1427 int aul_listen_app_launch_signal_v2(int (*func) (int, const char *, void *), void *data);
1428
1429 /**
1430  * @par Description:
1431  *      This API gets status of specified application process id.
1432  * @par Purpose:
1433  *      This API's purpose is to get the application's status.
1434  *
1435  * @param[in]   pid     pid of application
1436  * @return      0 or greater if success, nagative value if fail
1437  * @retval      STATUS_LAUNCHING
1438  * @retval      STATUS_CREATED
1439  * @retval      STATUS_FOCUS
1440  * @retval      STATUS_VISIBLE
1441  * @retval      STATUS_BG
1442  * @retval      STATUS_DYING
1443  * @retval      STATUS_HOME
1444  * @retval      STATUS_NORESTART
1445  * @see
1446  *      aul_status_update
1447  * @code
1448  * #include <aul.h>
1449  *
1450  * int iterfunc(const aul_app_info *info, void *data)
1451  * {
1452  *      int status;
1453  *      status = aul_app_get_status_bypid(info->pid);
1454  *      if (status == STATUS_FOCUS) {
1455  *              printf("%s has focus", info->app_id);
1456  *              (int *)data = info->pid;
1457  *              return -1;
1458  *      }
1459  *      return 0;
1460  * }
1461  *
1462  * int find_focus_app_pid()
1463  * {
1464  *      int pid = 0;
1465  *      aul_app_get_running_app_info(iterfunc, &pid);
1466  *      return pid;
1467  * }
1468  * @endcode
1469  * @remark
1470  *      This API is only available in User Session.
1471  */
1472 int aul_app_get_status_bypid(int pid);
1473
1474 /**
1475  * @par Description
1476  *      This API sets callback function that on application status changed.
1477  * @par Purpose:
1478  *      This API's purpose is to listen the application's status changed within
1479  *      the caller process. In general, a library that required to release resource on
1480  *      application's status may use this API.
1481  *
1482  * @param[in]   func    callback function
1483  * @param[in]   data    user data
1484  * @return      0 if success, negative value if fail
1485  * @retval      AUL_R_OK        - success
1486  * @retval      AUL_R_ERROR     - general error
1487  * @see
1488  *      aul_remove_status_local_cb
1489  * @code
1490  * #include <aul.h>
1491  *
1492  * int status_changed(int status, void *data)
1493  * {
1494  *      if (status == STATUS_FOCUS)
1495  *              printf("%d has focus\n", getpid());
1496  *
1497  *      if (status == STATUS_VISIBLE)
1498  *              printf("%d resume\n", getpid());
1499  *
1500  *      if (status == STATUS_BG0
1501  *              printf("%d pause\n", getpid());
1502  * }
1503  *
1504  * void listen_app_status()
1505  * {
1506  *      aul_add_status_local_cb(status_changed, NULL);
1507  * }
1508  * @endcode
1509  * @remark
1510  *      This API is only available in User Session.
1511  *
1512  */
1513 int aul_add_status_local_cb(int (*func) (int, void *), void *data);
1514
1515 /**
1516  * @par Description
1517  *      This API unsets callback function that on application status changed.
1518  * @par Purpose:
1519  *      This API's purpose is to remove callback that added by
1520  *      aul_add_status_local_cb.
1521  *
1522  * @param[in]   func    callback function
1523  * @param[in]   data    user data
1524  * @return      0 if success, negative value if fail
1525  * @retval      AUL_R_OK        - success
1526  * @retval      AUL_R_ERROR     - general error
1527  *
1528  * @see
1529  *      aul_add_status_local_cb
1530  * @code
1531  * #include <aul.h>
1532  *
1533  * int status_changed(int status, void *data)
1534  * {
1535  *      if (status == STATUS_FOCUS)
1536  *              printf("%d has focus\n", getpid());
1537  *
1538  *      if (status == STATUS_VISIBLE)
1539  *              printf("%d resume\n", getpid());
1540  *
1541  *      if (status == STATUS_BG0
1542  *              printf("%d pause\n", getpid());
1543  * }
1544  *
1545  * void listen_app_status()
1546  * {
1547  *      aul_add_status_local_cb(status_changed, NULL);
1548  * }
1549  *
1550  * void ignore_app_status()
1551  * {
1552  *      aul_remove_status_local_cb(status_changed, NULL);
1553  * }
1554  *
1555  * @endcode
1556  * @remark
1557  *      This API is only available in User Session.
1558  *
1559  */
1560 int aul_remove_status_local_cb(int (*func) (int, void *), void *data);
1561
1562 /*
1563  * This API is only for Appfw internally.
1564  */
1565 int aul_terminate_bgapp_pid(int pid);
1566
1567 /*
1568  * This API is only for Appfw internally.
1569  */
1570 int aul_terminate_pid_without_restart(int pid);
1571
1572 /*
1573  * This API is only for Appfw internally.
1574  */
1575 const char *aul_get_app_external_root_path(void);
1576
1577 /*
1578  * This API is only for Appfw internally.
1579  */
1580 const char *aul_get_app_root_path(void);
1581
1582 /*
1583  * This API is only for Appfw internally.
1584  */
1585 const char *aul_get_app_data_path(void);
1586
1587 /*
1588  * This API is only for Appfw internally.
1589  */
1590 const char *aul_get_app_cache_path(void);
1591
1592 /*
1593  * This API is only for Appfw internally.
1594  */
1595 const char *aul_get_app_resource_path(void);
1596
1597 /*
1598  * This API is only for Appfw internally.
1599  */
1600 const char *aul_get_app_tep_resource_path(void);
1601
1602 /*
1603  * This API is only for Appfw internally.
1604  */
1605 const char *aul_get_app_shared_data_path(void);
1606
1607 /*
1608  * This API is only for Appfw internally.
1609  */
1610 const char *aul_get_app_shared_resource_path(void);
1611
1612 /*
1613  * This API is only for Appfw internally.
1614  */
1615 const char *aul_get_app_shared_trusted_path(void);
1616
1617 /*
1618  * This API is only for Appfw internally.
1619  */
1620 const char *aul_get_app_external_data_path(void);
1621
1622 /*
1623  * This API is only for Appfw internally.
1624  */
1625 const char *aul_get_app_external_cache_path(void);
1626
1627 /*
1628  * This API is only for Appfw internally.
1629  */
1630 const char *aul_get_app_external_shared_data_path(void);
1631
1632 /*
1633  * This API is only for Appfw internally.
1634  */
1635 const char *aul_get_app_specific_path(void);
1636
1637 /*
1638  * This API is only for Appfw internally.
1639  */
1640 const char *aul_get_app_external_specific_path(void);
1641
1642 /*
1643  * This API is only for Appfw internally.
1644  */
1645 int aul_get_app_shared_data_path_by_appid(const char *app_id, char **path);
1646
1647 /*
1648  * This API is only for Appfw internally.
1649  */
1650 int aul_get_app_shared_resource_path_by_appid(const char *app_id, char **path);
1651
1652 /*
1653  * This API is only for Appfw internally.
1654  */
1655 int aul_get_app_shared_trusted_path_by_appid(const char *app_id, char **path);
1656
1657 /*
1658  * This API is only for Appfw internally.
1659  */
1660 int aul_get_app_external_shared_data_path_by_appid(const char *app_id, char **path);
1661
1662 /*
1663  * This API is only for Appfw internally.
1664  */
1665 int aul_get_usr_app_shared_data_path_by_appid(const char *app_id, char **path, uid_t uid);
1666
1667 /*
1668  * This API is only for Appfw internally.
1669  */
1670 int aul_get_usr_app_shared_resource_path_by_appid(const char *app_id, char **path, uid_t uid);
1671
1672 /*
1673  * This API is only for Appfw internally.
1674  */
1675 int aul_get_usr_app_shared_trusted_path_by_appid(const char *app_id, char **path, uid_t uid);
1676
1677 /*
1678  * This API is only for Appfw internally.
1679  */
1680 int aul_get_usr_app_external_shared_data_path_by_appid(const char *app_id, char **path, uid_t uid);
1681
1682 /*
1683  * This type is only for Appfw internally.
1684  */
1685 typedef int (*subapp_fn)(void *data);
1686
1687 /*
1688  * This API is only for Appfw internally.
1689  */
1690 int aul_set_subapp(subapp_fn cb, void *data);
1691
1692 /*
1693  * This API is only for Appfw internally.
1694  */
1695 int aul_subapp_terminate_request_pid(int pid);
1696
1697 /*
1698  * This API is only for Appfw internally.
1699  */
1700 int aul_is_subapp(void);
1701
1702 /*
1703  * This API is only for Appfw internally.
1704  */
1705 int aul_kill_pid(int pid);
1706
1707 /*
1708  * This API is only for Appfw internally.
1709  */
1710 int aul_add_caller_cb(int pid,  void (*caller_cb) (int, void *), void *data);
1711
1712 /*
1713  * This API is only for Appfw internally.
1714  */
1715 int aul_remove_caller_cb(int pid);
1716
1717 /*
1718  * This API is only for Appfw internally.
1719  */
1720 int aul_invoke_caller_cb(int pid);
1721
1722 /*
1723  * This API is only for Appfw internally.
1724  */
1725 void aul_set_preinit_window(void *evas_object);
1726
1727 /*
1728  * This API is only for Appfw internally.
1729  */
1730 void* aul_get_preinit_window(const char *win_name);
1731
1732 /*
1733  * This API is only for Appfw internally.
1734  */
1735 void aul_set_preinit_background(void *evas_object);
1736
1737 /*
1738  * This API is only for Appfw internally.
1739  */
1740 void* aul_get_preinit_background(void);
1741
1742 /*
1743  * This API is only for Appfw internally.
1744  */
1745 void aul_set_preinit_conformant(void *evas_object);
1746
1747 /*
1748  * This API is only for Appfw internally.
1749  */
1750 void* aul_get_preinit_conformant(void);
1751
1752 /*
1753  * This API is only for Appfw internally.
1754  */
1755 void aul_set_preinit_appid(const char *appid);
1756
1757 /*
1758  * This API is only for Appfw internally.
1759  */
1760 void aul_set_preinit_pkgid(const char *pkgid);
1761
1762 /*
1763  * This API is only for Appfw internally.
1764  */
1765 int aul_update_freezer_status(int pid, const char* type);
1766
1767 /*
1768  * This API is only for Appfw internally.
1769  */
1770 int aul_send_app_launch_request_signal(int pid, const char* appid, const char* pkgid, const char* type);
1771
1772 /*
1773  * This API is only for Appfw internally.
1774  */
1775 int aul_send_app_resume_request_signal(int pid, const char* appid, const char* pkgid, const char *type);
1776
1777 /*
1778  * This API is only for Appfw internally.
1779  */
1780 int aul_send_app_terminate_request_signal(int pid, const char* appid, const char* pkgid, const char *type);
1781
1782 /*
1783  * This API is only for Appfw internally.
1784  */
1785 int aul_send_app_status_change_signal(int pid, const char* appid, const char* pkgid, const char* status, const char *type);
1786
1787 /*
1788  * This API is only for Appfw internally.
1789  */
1790 int aul_send_app_terminated_signal(int pid);
1791
1792 /*
1793  * This API is only for Appfw internally.
1794  */
1795 int aul_send_app_group_signal(int owner_pid, int child_pid, const char *child_pkgid);
1796
1797 /*
1798  * This API is only for Appfw internally.
1799  */
1800 int aul_invoke_status_local_cb(int status);
1801
1802 /*
1803  * This type is only for Appfw internally.
1804  */
1805 typedef int (*data_control_provider_handler_fn) (bundle *b, int request_id, void *data);
1806
1807 /*
1808  * This API is only for Appfw internally.
1809  */
1810 int aul_set_data_control_provider_cb(data_control_provider_handler_fn handler);
1811
1812 /*
1813  * This API is only for Appfw internally.
1814  */
1815 int aul_unset_data_control_provider_cb(void);
1816
1817 /*
1818  * This API is only for Appfw internally.
1819  */
1820 int aul_pause_app(const char *appid);
1821
1822 /*
1823  * This API is only for Appfw internally.
1824  */
1825 int aul_pause_pid(int pid);
1826
1827 /*
1828  * This API is only for Appfw internally.
1829  */
1830 int aul_reload_appinfo(void);
1831
1832 /*
1833  * This API is only for Appfw internally.
1834  */
1835 int aul_status_update(int status);
1836
1837 /*
1838  * This API is only for Appfw internally.
1839  */
1840 int aul_running_list_update(char *appid, char *app_path, char *pid);
1841
1842 /*
1843  * This API is only for Appfw internally.
1844  */
1845 void aul_app_group_add(int leader_pid, int pid, int wid);
1846
1847 /*
1848  * This API is only for Appfw internally.
1849  */
1850 void aul_app_group_remove(int pid);
1851
1852 /*
1853  * This API is only for Appfw internally.
1854  */
1855 void aul_app_group_attach_window(int parent_wid, int child_wid);
1856
1857 /*
1858  * This API is only for Appfw internally.
1859  */
1860 void aul_app_group_detach_window(int child_wid);
1861
1862 /*
1863  * This API is only for Appfw internally.
1864  */
1865 int aul_app_group_get_window(int pid);
1866
1867 /*
1868  * This API is only for Appfw internally.
1869  */
1870 int aul_app_group_get_window(int pid);
1871
1872 /*
1873  * This API is only for Appfw internally.
1874  */
1875 int aul_app_group_set_window(int wid);
1876
1877 /*
1878  * This API is only for Appfw internally.
1879  */
1880 void aul_app_group_get_leader_pids(int *cnt, int **pids);
1881
1882 /*
1883  * This API is only for Appfw internally.
1884  */
1885 void aul_app_group_get_group_pids(int leader_pid, int *cnt, int **pids);
1886
1887 /*
1888  * This API is only for Appfw internally.
1889  */
1890 int aul_app_group_get_leader_pid(int pid);
1891
1892 /*
1893  * This API is only for Appfw internally.
1894  */
1895 int aul_app_group_clear_top(void);
1896
1897 /*
1898  * This API is only for Appfw internally.
1899  */
1900 int aul_app_group_is_top(void);
1901
1902 /*
1903  * This API is only for Appfw internally.
1904  */
1905 int aul_app_group_get_fg_flag(int pid);
1906
1907 /*
1908  * This API is only for Appfw internally.
1909  */
1910 void aul_app_group_lower(int *exit);
1911
1912 /*
1913  * This API is only for Appfw internally.
1914  */
1915 void aul_app_group_get_idle_pids(int *cnt, int **pids);
1916
1917 /*
1918  * This API is only for Appfw internally.
1919  */
1920 int aul_request_data_control_socket_pair(bundle *b, int *fd);
1921 /*
1922  * This API is only for Appfw internally.
1923  */
1924 int aul_request_message_port_socket_pair(int *fd);
1925 /*
1926  * This API is only for Appfw internally.
1927  */
1928 int aul_listen_booting_done_signal(int (*func) (int, void *), void *data);
1929
1930 /*
1931  * This API is only for Appfw internally.
1932  */
1933 int aul_listen_cooldown_signal(int (*func) (const char *, void *), void *data);
1934
1935 /*
1936  * This API is only for Appfw internally.
1937  */
1938 int aul_listen_app_status_signal(int (*func) (int, int, void *), void *data);
1939
1940 /*
1941  * This API is only for Appfw internally.
1942  */
1943 int aul_check_tep_mount(const char *tep_path);
1944
1945 /*
1946  * This API is only for Appfw internally.
1947  */
1948 int aul_is_tep_mount_dbus_done(const char *tep_string);
1949
1950 /*
1951  * This API is only for Appfw internally.
1952  */
1953 int aul_forward_app(const char *appid, bundle *kb);
1954
1955 /**
1956  * @par Description:
1957  *      This API create custom launchpad-loader
1958  * @par Purpose:
1959  *      This API's purpose is to make a slot for custom loader.
1960  *      Once it is made, added loader will make a candidate process to use.
1961  *
1962  * @param[in]   loader_path     The file name of the custom loader binary including full path
1963  * @return      Loader ID if success, negative value(<0) if fail
1964  *
1965  * @remark
1966  *      This API is only for Appfw internally.
1967  *      This API is only available in User Session.
1968 */
1969 int aul_add_loader(const char *loader_path);
1970
1971 /**
1972  * @par Description:
1973  *      This API destroy custom launchpad-loader
1974  * @par Purpose:
1975  *      This API's purpose is to remove a slot for custom loader.
1976  *      Once it is removed, the prepared process will be removed as well.
1977  *
1978  * @param[in]   loader_id       Loader ID
1979  * @return      0 if success, negative value(<0) if fail
1980  *
1981  * @remark
1982  *      This API is only for Appfw internally.
1983  *      This API is only available in User Session.
1984 */
1985 int aul_remove_loader(int loader_id);
1986
1987 /**
1988  * @par Description
1989  *      This API gets specified application process id.
1990  * @par Purpose:
1991  *      The purpose of this API is to get the pid of specified application.
1992  *
1993  * @param[in]   appid   application name
1994  * @return      callee's pid if success, negative value(<0) if fail
1995  *
1996  * @remark
1997  *      This API is only available in User Session.
1998  */
1999 int aul_app_get_pid(const char *appid);
2000
2001
2002 /**
2003  * @par Description:
2004  * This function delete rua history.
2005  *
2006  * @param[in] b Bundle object Target Package name or app path. If NULL or has no value, delete all rua history.
2007  *
2008  * @return 0 if success, negative value(<0) if fail
2009  * @see None
2010  * @remarks This API is only for Appfw internally.
2011  *
2012  * @par Sample code:
2013  * @code
2014 #include <aul.h>
2015
2016 ...
2017 {
2018     int r;
2019     bundle *b = bundle_create();
2020     if (pkg_name)
2021         bundle_add_str(b, AUL_K_RUA_PKGNAME, pkg_name);
2022     else if (app_path)
2023         bundle_add_str(b, AUL_K_RUA_APPPATH, app_path);
2024
2025     r = aul_delete_rua_history(b);
2026 }
2027
2028  * @endcode
2029  **/
2030 int aul_delete_rua_history(bundle *b);
2031
2032 #ifdef __cplusplus
2033         }
2034 #endif
2035
2036