include/aul.h

   1 /*
   2  *  aul
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>, Jaeho Lee <jaeho81.lee@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22
  23 #ifndef __AUL_H__
  24 #define __AUL_H__
  25
  26 #include <errno.h>
  27 #include <bundle.h>
  28 #include <sys/types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @mainpage
  36  *
  37  * This is new version of Application Utility Library
  38  *
  39  * Almost function's input param is application package name(APN).\n
  40  * APN is application package name which is set by developer.\n
  41  * In case of in-house application, prefix is org.tizen.\n
  42  * It is different from debian package name.\n
  43  *
  44  * - Debian Package Name : Name which is managed by package manager
  45  * - Application Package Name : Name which is used by AUL
  46  * - Execution Path : real program executable path
  47  */
  48
  49 /**
  50  * @open
  51  * @ingroup APPLICATION_FRAMEWORK
  52  * @defgroup aul  Application Utility Library
  53  * @{
  54  */
  55
  56
  57 /**
  58  * @file        aul.h
  59  * @brief       Application Utility Library header
  60  *
  61  * Patched by    Knhoon Baik <knhoon.baik@samsung.com>
  62  * Patched by    Youmin Ha   <youmin.ha@samsung.com>
  63  */
  64
  65 /**
  66  * @addtogroup aul
  67  * @{
  68  */
  69
  70 /**
  71  * @brief Return values in AUL.
  72  */
  73 typedef enum _aul_return_val {
  74         AUL_R_ENOAPP = -11,             /**< Failed to find app ID or pkg ID */
  75         AUL_R_ENOLAUNCHPAD = -10,       /**< no launchpad */
  76         AUL_R_ETERMINATING = -9,        /**< application terminating */
  77         AUL_R_EILLACC = -8,             /**< Illegal Access */
  78         AUL_R_LOCAL = -7,               /**< Launch by himself */
  79         AUL_R_ETIMEOUT = -6,            /**< Timeout */
  80         AUL_R_ECANCELED = -5,           /**< Operation canceled */
  81         AUL_R_EINVAL = -4,              /**< Invalid argument */
  82         AUL_R_ECOMM = -3,               /**< Comunication Error */
  83         AUL_R_ENOINIT = -2,             /**< AUL handler NOT initialized */
  84         AUL_R_ERROR = -1,               /**< General error */
  85         AUL_R_OK = 0                    /**< General success */
  86 }aul_return_val;
  87
  88 enum app_status {
  89         STATUS_LAUNCHING,
  90         STATUS_CREATED,
  91         STATUS_FOCUS,
  92         STATUS_VISIBLE,
  93         STATUS_BG,
  94         STATUS_DYING,
  95         STATUS_HOME
  96 };
  97
  98 /** @} */
  99
 100 /**
 101  * @defgroup aul_launch         Primitive APIs to launch/resume/terminate application
 102  * @ingroup aul
 103  * @brief
 104  *      APIs to launch/resume/terminate application
 105  *      - Launch application based on application package name
 106  *      - Resume application based on application package name
 107  *      - Resume application based on pid (required root or inhouse permisssion)
 108  *      - Terminate application base on pid (required root or inhouse permission)
 109  *
 110  *      AUL internal information
 111  *      - AUL grant pid, gid to launched application for security
 112  *      - AUL send RESET/RESUME/TERM event for running application in case of single instance
 113  *      - AUL set application enviroment based on desktop entry
 114  *      - AUL support single instance / multi instance
 115  *      - AUL support application data exchange format (bundle)
 116  */
 117
 118 /**
 119  * @addtogroup aul_launch
 120  * @{
 121  */
 122
 123 typedef enum _aul_type{
 124         AUL_START,
 125         AUL_RESUME,
 126         AUL_TERMINATE
 127 }aul_type;
 128
 129 /** AUL internal private key */
 130 #define AUL_K_PKG_NAME          "__AUL_PKG_NAME__"
 131 /** AUL internal private key */
 132 #define AUL_K_WAIT_RESULT       "__AUL_WAIT_RESULT__"
 133 /** AUL internal private key */
 134 #define AUL_K_SEND_RESULT       "__AUL_SEND_RESULT__"
 135 /** AUL internal private key */
 136 #define AUL_K_TASK_MANAGE       "__AUL_TASK_MANAGE__"
 137 /** AUL internal private key */
 138 #define AUL_K_APP_TYPE          "__AUL_APP_TYPE__"
 139 /** AUL internal private key - To check original caller's identity */
 140 #define AUL_K_ORG_CALLER_PID    "__AUL_ORG_CALLER_PID__"
 141 /** AUL internal private key - To check forwarded callee app's pid */
 142 #define AUL_K_FWD_CALLEE_PID    "__AUL_FWD_CALLEE_PID__"
 143
 144 /** AUL internal private key */
 145 #define AUL_K_NO_CANCEL        "__AUL_NO_CANCEL__"
 146
 147 /** AUL public key - To check caller's secuirty */
 148 #define AUL_K_CALLER_PID        "__AUL_CALLER_PID__"
 149 /** AUL public key - To check callee's secuirty */
 150 #define AUL_K_CALLEE_PID        "__AUL_CALLEE_PID__"
 151
 152 /** AUL public key - added for multiuser mode */
 153 #define AUL_K_CALLER_UID        "__AUL_CALLER_UID__"
 154 /** AUL public key - added for multiuser mode */
 155 #define AUL_K_CALLEE_UID        "__AUL_CALLEE_UID__"
 156
 157 /** AUL public key - To check caller's secuirty */
 158 #define AUL_K_CALLER_APPID      "__AUL_CALLER_APPID__"
 159 /** AUL public key - To check caller's secuirty */
 160 #define AUL_K_CALLEE_APPID      "__AUL_CALLEE_APPID__"
 161
 162 /** AUL public key - To find argv0 */
 163 #define AUL_K_ARGV0             "__AUL_ARGV0__"
 164 /** AUL public key - To measure launching time */
 165 #define AUL_K_STARTTIME         "__AUL_STARTTIME__"
 166
 167 /** AUL public key - To support launching based on mime type */
 168 #define AUL_K_MIME_TYPE         "__AUL_MIME_TYPE__"
 169 /** AUL public key - To support launching based on mime type */
 170 #define AUL_K_UNALIASED_MIME_TYPE               "__AUL_UNALIASED_MIME_TYPE__"
 171 /** AUL public key - To support launching based on mime type */
 172 #define AUL_K_MIME_CONTENT      "__AUL_MIME_CONTENT__"
 173
 174 /** AUL public key - To support launching based on service */
 175 #define AUL_K_SERVICE_NAME              "__AUL_SERVICE_NAME__"
 176
 177 /** AUL public key - To force launch app selector instead of lauchingn default app */
 178 #define AUL_K_FORCE_LAUNCH_APP_SELECTOR "__AUL_FORCE_LAUNCH_APP_SELECTOR__"
 179
 180 /** AUL public key - To support debug argument */
 181 #define AUL_K_DEBUG     "__AUL_DEBUG__"
 182
 183 /** AUL public key - To support SDK */
 184 #define AUL_K_SDK       "__AUL_SDK__"
 185
 186 /** AUL public key - To support Media key */
 187 #define AUL_K_MULTI_KEY "__AUL_MULTI_KEY__"
 188 /** AUL public key - To support Media key */
 189 #define AUL_K_MULTI_KEY_EVENT   "__AUL_MULTI_KEY_EVENT__"
 190
 191 /** AUL public bundle value */
 192 #define AUL_K_PRIVACY_APPID             "__AUL_PRIVACY_APPID__"
 193
 194
 195 /** AUL public bundle value - To support Media key*/
 196 #define AUL_V_KEY_PRESSED       "__AUL_KEY_PRESSED__"
 197 /** AUL public bundle value - To support Media key*/
 198 #define AUL_V_KEY_RELEASED      "__AUL_KEY_RELEASED__"
 199
 200 /** AUL internal private key */
 201 #define AUL_K_EXEC              "__AUL_EXEC__"
 202 /** AUL internal private key */
 203 #define AUL_K_MULTIPLE          "__AUL_MULTIPLE__"
 204 /** AUL internal private key */
 205 #define AUL_K_PACKAGETYPE       "__AUL_PACKAGETYPE__"
 206 /** AUL internal private key */
 207 #define AUL_K_HWACC             "__AUL_HWACC__"
 208
 209
 210 /** AUL internal private key */
 211 #define AUL_K_APPID             "__AUL_APPID__"
 212 /** AUL internal private key */
 213 #define AUL_K_PID               "__AUL_PID__"
 214 /** AUL internal private key - To support data control*/
 215 #define AUL_K_DATA_CONTROL_TYPE   "__AUL_DATA_CONTROL_TYPE__"
 216
 217 #define PRIVACY_POPUP "tizenprv00.privacy-popup"
 218
 219
 220 /**
 221  * @brief       This is callback function for aul_launch_init
 222  * @param[in]   type    event's type received from system
 223  * @param[in]   b       In case of RESET events, bundle which is received from peer
 224  * @param[in]   data    user-supplied data
 225  */
 226 typedef int (*aul_handler_fn) (aul_type type, bundle * b, void *data);
 227
 228 /**
 229  * @par Description:
 230  *      This API install your AUL handler and setup AUL internal connection.
 231  * @par Purpose:
 232  *      AUL receive START(RESET), RESUME, TERMINATE events from system.\n
 233  *      This API use to handle the events. \n
 234  * @par Typical use case:
 235  *      In general, you need not use this API.
 236  *      If you use AppCore, you should NOT use this API.
 237  *      AppCore will set default aul_handler.
 238  *
 239  * @param[in]   handler         aul main callback handler function
 240  * @param[in]   data            user-supplied data for start_handler
 241  * @return      0 if success, negative value(<0) if fail\n
 242  * @retval      AUL_R_OK        - success
 243  * @retval      AUL_R_ECANCELD  - aul handler was installed already by others
 244  * @retval      AUL_R_ECOMM     - error to create internal ipc
 245  * @retval      AUL_R_ERROR     - error to attach glib main loop
 246  *
 247  * @warning     If you use AppCore, you should NOT use this API.\n
 248  *              You need glib main loop.\n
 249  * @pre
 250  *      you must have aul handler to use this API.
 251  *      aul_luanch_init register aul handler.
 252  * @post
 253  *      None
 254  * @see
 255  *      None
 256  * @code
 257  * #include <aul.h>
 258  * #include <bundle.h>
 259  *
 260  * static int aul_handler(aul_type type, bundle *kb,void *data)
 261  * {
 262  *      switch(type)
 263  *      {
 264  *              case AUL_START:
 265  *                      // process RESET event
 266  *                      break;
 267  *              case AUL_RESUME:
 268  *                      // process RESUME event
 269  *                      break;
 270  *              case AUL_TERMINATE:
 271  *                      // preocess TERMINATE event
 272  *                      break;
 273  *      }
 274  *      return 0;
 275  * }
 276  *
 277  * static GMainLoop *mainloop = NULL;
 278  *
 279  * int main(int argc, char **argv)
 280  * {
 281  *      aul_launch_init(aul_handler,NULL);
 282  *      aul_launch_argv_handler(argc, argv);
 283  *
 284  *      mainloop = g_main_loop_new(NULL, FALSE);
 285  *      g_main_loop_run(mainloop);
 286  * }
 287  *
 288  * @endcode
 289  * @remark
 290  *      None
 291 */
 292 int aul_launch_init(aul_handler_fn handler, void *data);
 293
 294 /**
 295  * @par Description:
 296  *      This API create internal RESET events with given argc, argv \n
 297  * @par Purpose:
 298  *      This API's purpose is to generate reset event.
 299  *      If you want to generate local RESET events with argument vector format, use this API
 300  * @par Typical use case:
 301  *      In general, you need not use this API.
 302  *      AppCore use this API to create internal reset event.
 303  *
 304  * @param[in]   argc    # of args
 305  * @param[in]   argv    list of arg strings
 306  * @return      0 if success, negative value(<0) if fail
 307  * @retval      AUL_R_OK        - success
 308  * @retval      AUL_R_ENOINIT   - aul handler was NOT yet installed
 309  * @retval      AUL_R_ECANCLED  - error to create internal bundle with given argc,argv.
 310  * @retval      AUL_R_ERROR     - general error
 311  *
 312  * @pre
 313  *      you must have aul handler to use this API.
 314  *      aul_luanch_init register aul handler.
 315  * @post
 316  *      None
 317  * @see
 318  *      aul_launch_init
 319  * @code
 320  * #include <aul.h>
 321  * #include <bundle.h>
 322  *
 323  * int send_local_reset_event()
 324  * {
 325  *      int argc=3;
 326  *      char* argv[4];
 327  *      argv[0] = "local.app";
 328  *      argv[1] = "event_type";
 329  *      argv[2] = "my_reset";
 330  *      argv[3] = NULL;
 331  *      aul_launch_argv_handler(argc,argv);
 332  * }
 333  *
 334  * @endcode
 335  * @remark
 336  *      If you use AppCore, you NEED NOT use this API.
 337 */
 338 int aul_launch_argv_handler(int argc, char **argv);
 339
 340 /**
 341  * @par Description:
 342  *      This API creates internal RESET events with given bundle \n
 343  * @par Purpose:
 344  *  This API's purpose is to generate reset event.
 345  *  If you want to generate local RESET events with argument vector format, first use
 346  *  bundle_import_from_argv to create a bundle from the argument vector and then use this API
 347  *  Eventually, this API will replace aul_launch_argv_handler().
 348  * @par Typical use case:
 349  *      In general, you need not use this API.
 350  *      AppCore use this API to create internal reset event.
 351  *
 352  * @param[in]   b       bundle
 353  * @return      0 if success, negative value(<0) if fail
 354  * @retval      AUL_R_OK        - success
 355  * @retval      AUL_R_ENOINIT   - aul handler was NOT yet installed
 356  * @retval      AUL_R_ERROR     - general error
 357  *
 358  * @pre
 359  *      you must have aul handler to use this API.
 360  *      aul_luanch_init register aul handler.
 361  * @post
 362  *      None
 363  * @see
 364  *      aul_launch_init, bundle_import_from_argv
 365  * @code
 366  * #include <aul.h>
 367  * #include <bundle.h>
 368  *
 369  * int send_local_reset_event()
 370  * {
 371  *  bundle* b;
 372  *      int argc=3;
 373  *      char* argv[4];
 374  *      argv[0] = "local.app";
 375  *      argv[1] = "event_type";
 376  *      argv[2] = "my_reset";
 377  *      argv[3] = NULL;
 378  *
 379  *      b = bundle_import_from_argv(argc,argv);
 380  *      aul_launch_local(b);
 381  * }
 382  *
 383  * @endcode
 384  * @remark
 385  *      If you use AppCore, you NEED NOT to use this API.
 386 */
 387 int aul_launch_local(bundle *b);
 388
 389 /**
 390  * @par Description:
 391  *      This API launches application with the given bundle.
 392  *  If the application is not running or a multiple-instance one, this API launches with the given bundle.
 393  *      If the application is running, this API sends a RESET event to the App.
 394  *      While the application is running, if the application cannot receive the RESET event,
 395  *      this API returns a general error(AUL_R_ERROR).\n
 396  * @par Purpose:
 397  *      This API is for caller.
 398  *      This API's purpose is to launch/reset application with given bundle.
 399  * @par Typical use case:
 400  *      If you know the target application's pkgname and bundle types,
 401  *      you can use this API to launch/reset the application.
 402  *
 403  * @param[in]   pkgname         package name to be run as callee
 404  * @param[in]   kb              bundle to be passed to callee
 405  * @return      callee's pid if success, negative value(<0) if fail
 406  * @retval      AUL_R_OK        - success
 407  * @retval      AUL_R_EINVAL    - invaild package name
 408  * @retval      AUL_R_ECOM      - internal AUL IPC error
 409  * @retval      AUL_R_ERROR     - general error
 410  *
 411  * @pre
 412  *      None
 413  * @post
 414  *      None
 415  * @see
 416  *      aul_open_app
 417  * @code
 418  * #include <aul.h>
 419  * #include <bundle.h>
 420  *
 421  * int launch_inhouse_contact_app()
 422  * {
 423  *      bundle *b;
 424  *      b = bundle_create();
 425  *      bundle_add(b,"type","SIM");
 426  *      aul_launch_app("org.tizen.contact",b);
 427  * }
 428  *
 429  * @endcode
 430  * @remark
 431  *      None
 432  */
 433 int aul_launch_app(const char *appid, bundle *kb);
 434
 435 /**
 436  * @par Description:
 437  *  This API launches application, as menu screen launches the app.
 438  *  Thus, if the applocation is running, this API sends a RESUME event to the app.
 439  *  If the application is not running, this API launches the app.
 440  *  While the application is running, if the application cannot receive the RESUME event,
 441  *  AUL tries to raise the application's default window.
 442  *
 443  * @par Purpose:
 444  *      This API is for caller.
 445  *      This API's purpose is to resume/launch application
 446  * @par Typical use case:
 447  *      If you only want to show application with previous state or default state, Use this API.
 448  *
 449  * @param[in]   pkgname         package name to be resume as callee
 450  * @return      callee's pid if success, negative value(<0) if fail
 451  * @retval      AUL_R_OK        - success
 452  * @retval      AUL_R_EINVAL    - invaild package name
 453  * @retval      AUL_R_ECOM      - internal AUL IPC error
 454  * @retval      AUL_R_ERROR     - general error
 455  *
 456  * @pre
 457  *      None
 458  * @post
 459  *      None
 460  * @see
 461  *      aul_launch_app, aul_app_is_running, aul_resume_pid
 462  * @code
 463  * #include <aul.h>
 464  * #include <bundle.h>
 465  *
 466  * int open_inhouse_contact_app()
 467  * {
 468  *      if(aul_app_is_running("org.tizen.contact"))
 469  *              aul_open_app("org.tizen.contact");
 470  * }
 471  *
 472  * @endcode
 473  * @remark
 474  *      If you don't want to launch the app,
 475  *      you should check app's running state with aul_app_is_running.
 476  *      This API will launch the application if the application is not running.
 477 */
 478 int aul_open_app(const char *appid);
 479
 480 /**
 481  * @par Description:
 482  *      This API trigger to resume application
 483  *      If the application is running, this API send a resume event to the App.
 484  *      If the application is not running, this API returns fail.
 485  *      Although the application is running, if the application cannot receive resume event,
 486  *      AUL try to raise the application's default windows.
 487  * @par Purpose:
 488  *      This API is for caller.
 489  *      This API's purpose is to send resume event.
 490  * @par Typical use case:
 491  *      If you only want to show application with previous state or default state, Use this API.
 492  *
 493  * @param[in]   pkgname         package name to be resume as callee
 494  * @return      callee's pid if success, negative value(<0) if fail
 495  * @retval      AUL_R_OK        - success
 496  * @retval      AUL_R_EINVAL    - invaild package name
 497  * @retval      AUL_R_ECOM      - internal AUL IPC error
 498  * @retval      AUL_R_ERROR     - general error
 499  *
 500  * @pre
 501  *      None
 502  * @post
 503  *      None
 504  * @see
 505  *      aul_launch_app, aul_app_is_running, aul_resume_pid
 506  * @deprecated
 507  *  This function will be deprecated. Use aul_open_add() instead.
 508  * @code
 509  * #include <aul.h>
 510  * #include <bundle.h>
 511  *
 512  * int resume_inhouse_contact_app()
 513  * {
 514  *      if(aul_app_is_running("org.tizen.contact"))
 515  *              aul_resume_app("org.tizen.contact");
 516  * }
 517  *
 518  * @endcode
 519  * @remark
 520  *      If you don't want to launch the app,
 521  *      you should check app's running state with aul_app_is_running.
 522  *      This API will launch the application if the application is not running.
 523  *      If you want to only resume without launching in multiple instance application model,
 524  *      you should use aul_resume_pid.
 525 */
 526 int aul_resume_app(const char *appid);
 527
 528 /**
 529  * @par Description:
 530  *      This API trigger to resume application
 531  *      If the application is running, this API send a resume event to the App.
 532  *      If the application is not running, this API return AUL_R_ERROR.
 533  *      Although the application is running, if the application cannot receive resume event,
 534  *      AUL try to raise the application's default windows.
 535  * @par Purpose:
 536  *      This API is for caller.
 537  *      This API's purpose is to send resume event.
 538  * @par Typical use case:
 539  *      In multiple application model, If you want to only resume specific application, Use this API
 540  *
 541  * @param[in]   pid     application's pid to be resumed
 542  * @return      0 if success, negative value(<0) if fail
 543  * @retval      AUL_R_OK        - success
 544  * @retval      AUL_R_EINVAL    - invaild pid
 545  * @retval      AUL_R_ECOM      - internal AUL IPC error
 546  * @retval      AUL_R_ERROR     - general error (include application is not running)
 547  * @warning     This API need to require root or inhouse permisssion \n
 548  *              If you have not the permission, this API return AUL_R_ERROR. \n
 549  * @pre
 550  *      None
 551  * @post
 552  *      None
 553  * @see
 554  *      aul_launch_app
 555  * @code
 556  * #include <aul.h>
 557  * #include <bundle.h>
 558  *
 559  * int iterfunc(const aul_app_info *info, void *data)
 560  * {
 561  *      if(strcmp(info->pkg_name,"org.tizen.contact")==0)
 562  *              aul_resume_pid(info->pid);
 563  * }
 564  *
 565  * int iterate_running_apps()
 566  * {
 567  *      return aul_app_get_running_app_info(iterfunc,NULL);
 568  * }
 569  *
 570  * @endcode
 571  * @remark
 572  *      None
 573 */
 574 int aul_resume_pid(int pid);
 575
 576 /**
 577  * @par Description:
 578  *      This API trigger to terminate application
 579  *
 580  *      If the application is running, this API send a terminate event to the App. \n
 581  *      If the app cannot receive the event, AUL kill forcely the application.\n
 582  * @par Purpose:
 583  *      This API's purpose is to kill application
 584  * @par Typical use case:
 585  *      In general, Application like Task Manager use this API.
 586  *
 587  *              This API need to require root or inhouse permisssion. \n
 588  *
 589  * @param[in]   pid     application's pid to be terminated
 590  * @return      0 if success, negative value(<0) if fail
 591  * @retval      AUL_R_OK        - success
 592  * @retval      AUL_R_EINVAL    - invaild pid
 593  * @retval      AUL_R_ECOM      - internal AUL IPC error
 594  * @retval      AUL_R_ERROR     - general error
 595  * @warning     This API need to require root or inhouse permisssion. \n
 596  *
 597  * @pre
 598  *      None
 599  * @post
 600  *      None
 601  * @see
 602  *      None
 603  * @code
 604  * #include <aul.h>
 605  * #include <bundle.h>
 606  *
 607  * int iterfunc(const aul_app_info *info, void *data)
 608  * {
 609  *      if(strcmp(info->pkg_name,"org.tizen.contact")==0)
 610  *              aul_terminate_pid(info->pid);
 611  * }
 612  *
 613  * int iterate_running_apps()
 614  * {
 615  *      return aul_app_get_running_app_info(iterfunc,NULL);
 616  * }
 617  *
 618  * @endcode
 619  * @remark
 620  *      If you have not the permission, this API return AUL_R_ERROR. \n
 621 */
 622 int aul_terminate_pid(int pid);
 623
 624 /** @} */
 625
 626 /**
 627  * @defgroup aul_info           Helper APIs to get running application information
 628  * @ingroup aul
 629  * @brief
 630  *      API to get running application information (state, executable path, ..)
 631  *      - get application package name from pid
 632  *      - get application running state
 633  *      - get application list of runnning applications
 634  */
 635
 636 /**
 637  * @addtogroup aul_info
 638  * @{
 639  */
 640
 641 /**
 642  *@brief Running application's information structure retrieved by AUL
 643  */
 644 typedef struct _aul_app_info {
 645         int pid;                /**< app's pid if running*/
 646         char* pkg_name;         /**< application id */
 647         char* app_path;         /**< application excutable path */
 648         char* appid;
 649 } aul_app_info;
 650
 651 /**
 652  * @brief iterator function running with aul_app_get_running_app_info
 653  * @param[out]  ainfo   aul_app_info retreived by aul_app_get_running_app_info
 654  * @param[out]  data    user-supplied data
 655 */
 656 typedef int (*aul_app_info_iter_fn)(const aul_app_info *ainfo, void *data);
 657
 658 /**
 659  * @par Description:
 660  *      This API ask a application is running by application package name.
 661  * @par Purpose:
 662  *      To know whether some application is running or not, use this API
 663  * @par Typical use case:
 664  *      For example, If you want to know browser application running,
 665  *      you can check it by using this API.
 666  *
 667  * @param[in]   pkgname application package name
 668  * @return      true / false
 669  * @retval      1       app_name is running now.
 670  * @retval      0       app_name is NOT running now.
 671  *
 672  * @pre
 673  *      None
 674  * @post
 675  *      None
 676  * @see
 677  *      None
 678  * @code
 679  * #include <aul.h>
 680  *
 681  * int is_running_browser_app()
 682  * {
 683  *      return aul_app_is_running("org.tizen.browser");
 684  * }
 685  *
 686  * @endcode
 687  * @remark
 688  *      None
 689 *
 690 */
 691 int aul_app_is_running(const char *appid);
 692
 693 /**
 694  * @par Description:
 695  *      This API use to get running application list.
 696  *      This API call iter_fn with each aul_app_info of running apps when running application is found.
 697  * @par Purpose:
 698  *      If you want to get running application list, use this API
 699  *      This API give you running applications which has SLP desktop file.
 700  * @par Typical use case:
 701  *      In general, this API is used by task manager appllication. (running application list viewer)
 702  *
 703  * @param[in]   iter_fn         iterator function
 704  * @param[in]   data            user-supplied data for iter_fn
 705  * @return      0 if success, negative value(<0) if fail
 706  * @retval      AUL_R_OK        - success
 707  * @retval      AUL_R_ERROR     - internal error
 708  *
 709  * @pre
 710  *      None
 711  * @post
 712  *      None
 713  * @see
 714  *      None
 715  * @code
 716  * #include <aul.h>
 717  *
 718  * int iterfunc(const aul_app_info* info, void* data)
 719  * {
 720  *      printf("\t==========================\n");
 721  *      printf("\t pkg_name: %s\n", info->appid);
 722  *      printf("\t app_path: %s\n", info->app_path);
 723  *      printf("\t running pid: %d\n", info->pid);
 724  *      printf("\t==========================\n");
 725  *      return 0;
 726  * }
 727  *
 728  * int iterate_running_apps()
 729  * {
 730  *      return aul_app_get_running_app_info(iterfunc,NULL);
 731  * }
 732  *
 733  * @endcode
 734  * @remark
 735  *      This API should use if you want to know running application which has desktop files.
 736  *      If you want to get all process list, you must iterate process information by using proc filesystem
 737  *      Or, If you want to get all window list, you must iterate XWindows by using XWindow APIs
 738  */
 739 int aul_app_get_running_app_info(aul_app_info_iter_fn iter_fn, void *data);
 740
 741 /**
 742  * @par Description:
 743  *      This API get application package name by pid
 744  * @par Purpose:
 745  *      If you want to get package name of running application, use this API
 746  * @par Typical use case:
 747  *      In general, You can use this API when you want to know caller's information.
 748  *
 749  * @param[in]   pid             given pid
 750  * @param[out]  pkgname         pkgname to be get
 751  * @param[in]   len             length of pkgname
 752  * @return      0 if success, negative value(<0) if fail
 753  * @retval      AUL_R_OK        - success
 754  * @retval      AUL_R_ERROR     - no such a package name
 755  * @pre
 756  *      None
 757  * @post
 758  *      None
 759  * @see
 760  *      None
 761  * @code
 762  * #include <aul.h>
 763  * #include <bundle.h>
 764  *
 765  * static int app_reset(bundle *b, void *data)
 766  * {
 767  *      int pid;
 768  *      char appname[255];
 769  *
 770  *      pid = atoi(bundle_get_val(b,AUL_K_CALLER_PID));
 771  *      aul_app_get_pkgname_bypid(pid, appname, sizeof(appname));
 772  * }
 773  *
 774  * @endcode
 775  * @remark
 776  *      None
 777 */
 778 int aul_app_get_pkgname_bypid(int pid, char *pkgname, int len);
 779
 780 /**
 781  * @par Description:
 782  *      This API get application appid by pid
 783  * @par Purpose:
 784  *      If you want to get appid of running application, use this API
 785  * @par Typical use case:
 786  *      In general, You can use this API when you want to know caller's information.
 787  *
 788  * @param[in]   pid             given pid
 789  * @param[out]  appid           application id
 790  * @param[in]   len             length of pkgname
 791  * @return      0 if success, negative value(<0) if fail
 792  * @retval      AUL_R_OK        - success
 793  * @retval      AUL_R_ERROR     - no such a appid
 794  * @pre
 795  *      None
 796  * @post
 797  *      None
 798  * @see
 799  *      None
 800  * @code
 801  * #include <aul.h>
 802  * #include <bundle.h>
 803  *
 804  * static int app_reset(bundle *b, void *data)
 805  * {
 806  *      int pid;
 807  *      char appid[255];
 808  *
 809  *      pid = atoi(bundle_get_val(b,AUL_K_CALLER_PID));
 810  *      aul_app_get_appid_bypid(pid, appid, sizeof(appid));
 811  * }
 812  *
 813  * @endcode
 814  * @remark
 815  *      None
 816 */
 817 int aul_app_get_appid_bypid(int pid, char *appid, int len);
 818
 819
 820 /** @} */
 821
 822 /**
 823  * @defgroup aul_mime High-level APIs to launch default application based on mime type
 824  * @ingroup aul
 825  * @brief
 826  *   AUL High-level APIs based on mime type
 827  *
 828  *   These APIs provide two functionality\n
 829  *
 830  *   -# To launch default application to open a file based on its MIME type \n
 831  *   For example, you can launch the default video player to open .mp4 files
 832  *   or launch the default browser to open HTML files \n
 833  *   -# To launch default application to process given content \n
 834  *   For example, you can launch the default e-mail application to process
 835  *   "nice@samsung.com" e-mail address.
 836  */
 837
 838 /**
 839  * @addtogroup aul_mime
 840  * @{
 841  */
 842
 843 /**
 844  * @par Description:
 845  *      This API launch application associated with given filename
 846  * @par Purpose:
 847  *      This API is for caller.
 848  *      This API launch application based on mime type.
 849  *      This API find mime_type associated with file name,
 850  *      and then find default app associated with found mime_type
 851  *      and then launch the app with filename argument.
 852  * @par Typical use case:
 853  *      You can launch application to process given filename.
 854  *      That is, Even if you don't know the specific application's pkgname,
 855  *      you can launch the applicaiton processing given filename .
 856  *      For example, If you want to process image file, you can simply launch image viewer.
 857  *      At that time, you can use this APIs like aul_open_file("myimage.jpg");
 858  *
 859  * @param[in]   filename        filename
 860  * @return      callee's pid or 0 if success, negative value if fail\n
 861  *              (when no found default app, return 0)
 862  * @retval      AUL_R_OK        - success
 863  * @retval      AUL_R_EINVAL    - invalid argument(filename)
 864  * @retval      AUL_R_ECOM      - internal AUL IPC error
 865  * @retval      AUL_R_ERROR     - general error
 866  *
 867  * @pre
 868  *      None
 869  * @post
 870  *      None
 871  * @see
 872  *      None
 873  * @code
 874  * #include <aul.h>
 875  *
 876  * int view_image_file(char *filename)
 877  * {
 878  *      aul_open_file(filename);
 879  * }
 880  *
 881  * @endcode
 882  * @remark
 883  *      None
 884  *
 885  */
 886 int aul_open_file(const char* filename);
 887
 888 /**
 889  * @par Description:
 890  *      This API launch application associated with given specific mimetype
 891  * @par Purpose:
 892  *      This API is for caller.
 893  *      This API launch application based on mime type like aul_open_file API.
 894  *      But, This API don't find mime_type associated with file name.
 895  *      This API use mimetype given by user. By using given mimetype, find default application.
 896  *      and then launch the app with filename argument.
 897  * @par Typical use case:
 898  *      Some files cannot extract exact mimetype automatically.
 899  *      For example, To know mime type of files with DRM lock, first we should unlock DRM file.
 900  *      In this case, You can use this API.
 901  *      First, unlock DRM file, and extract mimetype from unlock file by using aul_get_mime_from_file,
 902  *      and then, use this API with DRM file and extracted mime type.
 903  *
 904  * @param[in]   filename        filename
 905  * @param[in]   mimetype        specific mimetype
 906  * @return      callee's pid or 0 if success, negative value if fail\n
 907  *              (when no found default app, return 0)
 908  * @retval      AUL_R_OK        - success
 909  * @retval      AUL_R_EINVAL    - invalid argument(filename,mimetype)
 910  * @retval      AUL_R_ECOM      - internal AUL IPC error
 911  * @retval      AUL_R_ERROR     - general error
 912  *
 913  * @pre
 914  *      None
 915  * @post
 916  *      None
 917  * @see
 918  *      aul_open_file, aul_get_mime_from_file
 919  * @code
 920  * #include <aul.h>
 921  *
 922  * int view_drm_image_file(char *drm_filename)
 923  * {
 924  *      char* mimetype;
 925  *      // you must implement this function
 926  *      mimetype = get_mimetype_from_drmfile(drm_filename);
 927  *
 928  *      aul_open_file_with_mimetype(drm_filename,mimetype);
 929  * }
 930  *
 931  * @endcode
 932  * @remark
 933  *      None
 934  */
 935 int aul_open_file_with_mimetype(const char *filename, const char *mimetype);
 936
 937 /**
 938  * @par Description:
 939  *      This API launch application associated with content like "http://www.samsung.com"
 940  * @par Purpose:
 941  *      This API is for caller.
 942  *      This API launch application based on mime type.
 943  *      This API find mime_type associated with content,
 944  *      and then find default app associated with found mime_type,
 945  *      and then launch the app with content argument.
 946  * @par Typical use case:
 947  *      You can launch application to process given content.
 948  *      That is, Even if you don't know the specific application's pkgname,
 949  *      you can launch the applicaiton processing given content.
 950  *      For example, If you want to process URL "http://www.samsung.com",
 951  *      you can simply launch browser.
 952  *      At that time, you can use this APIs like aul_open_content("http://www.samsung.com");
 953  *
 954  * @param[in]   content         content
 955  * @return      callee's pid or 0 if success, negative value if fail\n
 956  *              (when no found default app, return 0)
 957  * @retval      AUL_R_OK        - success
 958  * @retval      AUL_R_EINVAL    - invalid argument(content)
 959  * @retval      AUL_R_ECOM      - internal AUL IPC error
 960  * @retval      AUL_R_ERROR     - general error or no found mimetype
 961  *
 962  * @pre
 963  *      None
 964  * @post
 965  *      None
 966  * @see
 967  *      None
 968  * @code
 969  * #include <aul.h>
 970  *
 971  * int view_url(char *url)
 972  * {
 973  *      aul_open_content(url);
 974  * }
 975  *
 976  * @endcode
 977  * @remark
 978  *      None
 979  *
 980  */
 981 int aul_open_content(const char* content);
 982
 983 /**
 984  * @par Description:
 985  *       This API get the default application(appid) associated with MIME type
 986  * @par Purpose:
 987  *      This API use to get default application associteted with mimetype
 988  *      In general, Setting Application need this API.
 989  * @par Typical use case:
 990  *      Setting Application show mapping of default application / mimetype
 991  *
 992  * @param[in]   mimetype        a mime type
 993  * @param[out]  defapp          a application appid of the app
 994  * @param[in]   len             length of defapp
 995  * @return      0 if success, negative value if fail
 996  * @retval      AUL_R_OK        - success
 997  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
 998  * @retval      AUL_R_ERROR     - general error or no found mimetype
 999  *
1000  * @pre
1001  *      None
1002  * @post
1003  *      None
1004  * @see
1005  *      aul_set_defapp_with_mime
1006  * @code
1007  * #include <aul.h>
1008  *
1009  * void get_text_html_defapp()
1010  * {
1011  *      char appname[255];
1012  *      aul_get_defapp_from_mime("text/html",appname,sizeof(appname));
1013  * }
1014  *
1015  * @endcode
1016  * @remark
1017  *      None
1018  *
1019  */
1020 int aul_get_defapp_from_mime(const char *mimetype, char *defapp, int len);
1021
1022 /**
1023  * @par Description:
1024  *       This API set the default application(appid) associated with MIME type
1025  * @par Purpose:
1026  *      This API use to change default application associteted with mimetype
1027  *      In general, Setting Application or Installer need this API.
1028  * @par Typical use case:
1029  *      Default Application associated with mimetype can be changed by Setting Application or installer
1030  *      So, application to process specific mimetype can be substituted.
1031  *
1032  * @param[in]   mimetype        a mime type
1033  * @param[in]   defapp          a application appid of the app to be set
1034  * @return      0 if success, negative value if fail
1035  * @retval      AUL_R_OK        - success
1036  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
1037  * @retval      AUL_R_ERROR     - general error
1038  *
1039  * @pre
1040  *      None
1041  * @post
1042  *      None
1043  * @see
1044  *      aul_get_defapp_from_mime
1045  * @code
1046  * #include <aul.h>
1047  *
1048  * void set_text_html_defapp()
1049  * {
1050  *      aul_set_defapp_with_mime("text/html","org.tizen.browser");
1051  * }
1052  *
1053  * @endcode
1054  * @remark
1055  *      None
1056 */
1057 int aul_set_defapp_with_mime(const char *mimetype, const char *defapp);
1058
1059 /**
1060  * @par Description:
1061  *      This API get the mimetype associated with filename
1062  * @par Purpose:
1063  *      This API use to get mimetype associteted with given filename
1064  *      In general, This API use when you want to know only mimetype given filename.
1065  * @par Typical use case:
1066  *      For example, In trasfering data through bluetooth,
1067  *      additional information like mimetype should be added.
1068  *      In such situation, You can get mimetype by using this API.
1069  *
1070  * @param[in]   filename        file name
1071  * @param[out]  mimetype        a mime type
1072  * @param[in]   len             length of mimetype
1073  * @return      0 if success, negative value if fail
1074  * @retval      AUL_R_OK        - success
1075  * @retval      AUL_R_EINVAL    - invalid argument(filename)
1076  * @retval      AUL_R_ERROR     - general error
1077  *
1078  * @pre
1079  *      None
1080  * @post
1081  *      None
1082  * @see
1083  *      None
1084  * @code
1085  * #include <aul.h>
1086  *
1087  * void get_mimetype()
1088  * {
1089  *      char mimetype[255];
1090  *      aul_get_mime_from_file("image.jpg",mimetype,sizeof(mimetype));
1091  * }
1092  *
1093  * @endcode
1094  * @remark
1095  *      None
1096  */
1097 int aul_get_mime_from_file(const char *filename, char *mimetype, int len);
1098
1099 /**
1100  * @par Description:
1101  *      This API get the mimetype associated with given content
1102  * @par Purpose:
1103  *      This API use to get mimetype associteted with given content
1104  *      In general, This API use when you want to know only mimetype given content
1105  * @par Typical use case:
1106  *      For example, In trasfering data through bluetooth,
1107  *      additional information like mimetype should be added.
1108  *      In such situation, You can get mimetype by using this API.
1109  *
1110  * @param[in]   content         content string like "011-0000-0000"
1111  * @param[out]  mimetype        a mime type
1112  * @param[in]   len             length of mimetype
1113  * @return      0 if success, negative value if fail
1114  * @retval      AUL_R_OK        - success
1115  * @retval      AUL_R_EINVAL    - invalid argument(content)
1116  * @retval      AUL_R_ERROR     - general error
1117  *
1118  * @pre
1119  *      None
1120  * @post
1121  *      None
1122  * @see
1123  *      None
1124  * @code
1125  * #include <aul.h>
1126  *
1127  * void get_mimetype()
1128  * {
1129  *      char mimetype[255];
1130  *      aul_get_mime_from_content("http://www.samsung.com",mimetype,sizeof(mimetype));
1131  * }
1132  *
1133  * @endcode
1134  * @remark
1135  *      None
1136 */
1137 int aul_get_mime_from_content(const char *content, char *mimetype, int len);
1138
1139 /**
1140  * @par Description:
1141  *      This API get the icon's name associated with given mimetype
1142  * @par Purpose:
1143  *      This API use to get icon's name associteted with given mimetype
1144  * @par Typical use case:
1145  *      If you want to show mimetype's icon, use this API.
1146  *
1147  * @param[in]   mimetype        a mime type
1148  * @param[out]  iconname        icon's name
1149  * @param[in]   len             length of iconname
1150  * @return      0 if success, negative value if fail
1151  * @retval      AUL_R_OK        - success
1152  * @retval      AUL_R_EINVAL    - invalid argument(content)
1153  * @retval      AUL_R_ERROR     - general error (no such mime type)
1154  *
1155  * @pre
1156  *      None
1157  * @post
1158  *      None
1159  * @see
1160  *      None
1161  * @code
1162  * #include <aul.h>
1163  *
1164  * void get_mime_icon()
1165  * {
1166  *      char icon[255];
1167  *      aul_get_mime_icon("text/html",icon,sizeof(icon));
1168  * }
1169  *
1170  * @endcode
1171  * @remark
1172  *      None
1173  */
1174 int aul_get_mime_icon(const char *mimetype, char *iconname, int len);
1175
1176 /**
1177  * @par Description:
1178  *      This API get the extensions associated with given mimetype
1179  * @par Purpose:
1180  *      This API use to get extensions associteted with given mimetype
1181  * @par Typical use case:
1182  *      In general, user is not familiar with mimetype(text/html),
1183  *      user is familiar with extenstions(*.html, *.htm)
1184  *      So, To show mimetype information to user, use this API
1185  *
1186  * @param[in]   mimetype        a mime type
1187  * @param[out]  extlist         extentions (ex> mpeg,mpg,mpe)
1188  * @param[in]   len             length of extlist
1189  * @return      0 if success, negative value if fail
1190  * @retval      AUL_R_OK        - success
1191  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
1192  * @retval      AUL_R_ERROR     - general error (no mimetype or no extenstion)
1193  *
1194  * @pre
1195  *      None
1196  * @post
1197  *      None
1198  * @see
1199  *      aul_get_mime_description
1200  * @code
1201  * #include <aul.h>
1202  *
1203  * void get_extension()
1204  * {
1205  *      char extlist[255];
1206  *      aul_get_mime_extension("text/html",extlist,sizeof(extlist));
1207  * }
1208  *
1209  * @endcode
1210  * @remark
1211  *      Some mimetype don't have extension.
1212  *      In that case, You can use aul_get_mime_description.
1213  *
1214 */
1215 int aul_get_mime_extension(const char *mimetype, char *extlist, int len);
1216
1217 /**
1218  * @par Description:
1219  *      This API get the description associated with given mimetype
1220  * @par Purpose:
1221  *      This API use to get description associteted with given mimetype
1222  * @par Typical use case:
1223  *      In general, user is not familiar with mimetype(text/html),
1224  *      user is familiar with well-knowing information like extenstions(*.html, *.htm)
1225  *      But, some mimetype don't have extenstion.
1226  *      At that time,to show mimetype information to user, use this API
1227  *
1228  * @param[in]   mimetype        a mime type
1229  * @param[out]  desc            description (ex> Call client)
1230  * @param[in]   len             length of desc
1231  * @return      0 if success, negative value if fail
1232  * @retval      AUL_R_OK        - success
1233  * @retval      AUL_R_EINVAL    - invalid argument(mimetype)
1234  * @retval      AUL_R_ERROR     - general error (no mimetype or no descrition)
1235  *
1236  * @pre
1237  *      None
1238  * @post
1239  *      None
1240  * @see
1241  *      aul_get_mime_extension
1242  * @code
1243  * #include <aul.h>
1244  *
1245  * void get_information_from_mime()
1246  * {
1247  *      char info[255];
1248  *      if(aul_get_mime_extension("text/html",info,sizeof(info))<0){
1249  *              aul_get_mime_description("text/html",info,sizeof(info));
1250  *      }
1251  * }
1252  *
1253  * @endcode
1254  * @remark
1255  *      None
1256  */
1257 int aul_get_mime_description(const char *mimetype, char *desc, int len);
1258
1259 /************************************************************************************************/
1260 /* Example of aul_open_content or aul_open_file                                                 */
1261 /* voice call , browser , docview , image viewer , audio player, video player                   */
1262 /*                                                                                              */
1263 /* voice call - aul_open_content("callto://011-1111-1111");                                     */
1264 /* browser -    aul_open_content("http://www.naver.com");                                       */
1265 /*         -    aul_open_file("/opt/share/index.html");                                         */
1266 /* docview -    aul_open_file("/opt/share/word.pdf");                                           */
1267 /* image view - aul_open_file("/opt/share/image.jpg");                                          */
1268 /* audio play - aul_open_file("/opt/share/audio.mp3");                                          */
1269 /* video play - aul_open_file("/opt/share/video.mpg");                                          */
1270 /************************************************************************************************/
1271
1272 /** @} */
1273
1274 /**
1275  * @defgroup aul_service High-level APIs to launch applications based on service.
1276  * @ingroup aul
1277  * @brief
1278  *      AUL High-level APIs based on service
1279  *
1280  *      This is Request/Response mechanism based on AUL like DBUS service call with auto-activation.\n
1281  *      We recommend this APIs for requesting application service like camera application service (take_picture)
1282  *      But, You can use other mechanism like DBUS service or your own internal IPC
1283  *
1284  *      - Caller\n
1285  *        Launch application based on service \n
1286  *        If application is not running, AUL requests to reset the event.\n
1287  *        Application can wait result with callback function.
1288  *
1289  *      - Callee\n
1290  *        After callee performs the requested operation, callee sends the result back, if necessary.\n
1291  *
1292  */
1293
1294 /**
1295  * @addtogroup aul_service
1296  * @{
1297  */
1298
1299 /**
1300  * @brief aul_service_res_fn is service result function
1301  * @param[out]  b       result bundle
1302  * @param[out]  data    user-supplied data
1303 */
1304 typedef void (*aul_service_res_fn)(bundle *b, int reserved, void *user_data);
1305
1306 /**
1307  * @par Description:
1308  *      This API launch application based on service.
1309  * @par Purpose:
1310  *      This API is for caller.
1311  *      This API launch application based on service name.
1312  *      This API find default application associated with service name.
1313  *      and then launch the application with given bundle.
1314  * @par Typical use case:
1315  *      You can launch application provided the service if you know service name.
1316  *      That is, even if you don't know the specific application's pkgname,
1317  *      you can launch the applicaiton by requesting the service.
1318  *      For example, If you want to take a picture in your app, you can simply launch camera application.
1319  *      At that time, you can use this API like aul_open_service(TAKE_PICTURE_SVC,..);
1320  *
1321  *
1322  * @param[in]   svcname         service name to launch as callee
1323  * @param[in]   b               bundle to be passed to callee
1324  * @param[in]   cbfunc          result callback function
1325  * @param[in]   data            user-supplied data passed to callback function
1326  * @return      callee's pid if success, negative value(<0) if fail
1327  * @retval      AUL_R_OK        - success
1328  * @retval      AUL_R_EINVAL    - invaild service name
1329  * @retval      AUL_R_ENOINIT   - you must initilize aul library with aul_launch_init
1330  * @retval      AUL_R_ECOM      - internal AUL IPC error
1331  * @retval      AUL_R_ERROR     - general error
1332  *
1333  * @pre
1334  *      None
1335  * @post
1336  *      None
1337  * @see
1338  *      None
1339  * @code
1340  * #include <aul.h>
1341  * #include <aul_service.h>
1342  * #include <bundle.h>
1343  *
1344  * void res_func(bundle *b, int reserved, void *user_data)
1345  * {
1346  *      // process result bundle
1347  * }
1348  *
1349  * int create_camera_view()
1350  * {
1351  *      aul_open_service(TAKE_PICTURE_SVC, NULL, res_func, NULL);
1352  * }
1353  *
1354  * @endcode
1355  * @remark
1356  *      This API can wait result (asynchronous).
1357  *      To see kinds of default service provided by platform, see "aul_service.h" header file
1358  *
1359  */
1360 int aul_open_service(const char *svcname, bundle *b, aul_service_res_fn cbfunc, void *data);
1361
1362 /**
1363  * @par Description:
1364  *      This API create service result bundle based on bundle received in reset event.
1365  * @par Purpose:
1366  *      This API use to create result bundle to send it to caller.
1367  * @par Typical use case:
1368  *      This API is for callee which provide application service.\n
1369  *      To send result to caller, You must create result bundle. \n
1370  *      Callee(application providing the service) can send result by using this API and aul_send_service_result.
1371  *
1372  * @param[in]   inb             bundle received in reset event
1373  * @param[out]  outb            bundle to use for returning result
1374  * @return      0 if success, negative value(<0) if fail
1375  * @retval      AUL_R_OK        - success
1376  * @retval      AUL_R_EINVAL    - inb is not bundle created by aul_open_service
1377  * @retval      AUL_R_ERROR     - general error
1378  *
1379  * @pre
1380  *      To create result bundle, You need received original bundle.
1381  *      The original bundle can get from app_reset handler.
1382  * @post
1383  *      None
1384  * @see
1385  *      aul_send_service_result
1386  * @code
1387  * #include <aul.h>
1388  * #include <bundle.h>
1389  *
1390  * int app_reset(bundle *b, void *data)
1391  * {
1392  *      ad->recved_bundle = bundle_dup(b);
1393  * }
1394  *
1395  * int click_ok()
1396  * {
1397  *      bundle* res_bundle;
1398  *      aul_create_result_bundle(ad->recved_bundle,&res_bundle);
1399  *      bundle_add(res_bundle, "result", "1");
1400  *      aul_send_service_result(res_bundle);
1401  * }
1402  * @endcode
1403  * @remark
1404  *      None
1405  *
1406  */
1407 int aul_create_result_bundle(bundle *inb, bundle **outb);
1408
1409 /**
1410  * @par Description:
1411  *      This API send service result to caller with bundle
1412  * @par Purpose:
1413  *      This API is used to send result bundle to caller.
1414  * @par Typical use case:
1415  *      This API is for callee which provide application service.\n
1416  *      To send result to caller, You can use this API after creating result bundle. \n
1417  *      Callee(application to provide service) can send result by using this API and aul_create_result_bundle.
1418  *
1419  * @param[in]   b      Result data in bundle format
1420  * @return      0 if success, negative value(<0) if fail
1421  * @retval      AUL_R_OK        - success
1422  * @retval      AUL_R_EINVAL    - invalid result bundle
1423  * @retval      AUL_R_ECOMM     - internal AUL IPC error
1424  * @retval      AUL_R_ERROR     - general error
1425  *
1426  * @pre
1427  *      To send result bundle, You must create result bundle.
1428  *      see aul_create_result_bundle
1429  * @post
1430  *      None
1431  * @see
1432  *      aul_create_result_bundle
1433  * @code
1434  * #include <aul.h>
1435  * #include <bundle.h>
1436  *
1437  * int app_reset(bundle *b, void *data)
1438  * {
1439  *      ad->recved_bundle = bundle_dup(b);
1440  * }
1441  *
1442  * int click_ok()
1443  * {
1444  *      bundle* res_bundle;
1445  *      aul_create_result_bundle(ad->recved_bundle,&res_bundle);
1446  *      bundle_add(res_bundle, "result", "1");
1447  *      aul_send_service_result(res_bundle);
1448  * }
1449  * @endcode
1450  * @remark
1451  *      None
1452  *
1453  */
1454 int aul_send_service_result(bundle *b);
1455
1456 /**
1457  * @par Description:
1458  *      This API set the default application(appid) associated with service name
1459  * @par Purpose:
1460  *      This API use to change default application associteted with service name
1461  *      In general, Setting Application needs this API.
1462  * @par Typical use case:
1463  *      Default Application associated with service name can be changed by Setting Application
1464  *      So, Inhouse service application can be substituted by 3rd party service application
1465  *
1466  * @param[in]   svcname         service string like "create_contact"
1467  * @param[in]   defapp          default application like "com.samsung.contact"
1468  * @return      0 if success, negative value if fail
1469  * @retval      AUL_R_OK        - success
1470  * @retval      AUL_R_EINVAL    - invalid argument(content)
1471  * @retval      AUL_R_ERROR     - general error
1472  *
1473  * @pre
1474  *      None
1475  * @post
1476  *      None
1477  * @see
1478  *      aul_get_defapp_for_service
1479  * @code
1480  * #include <aul.h>
1481  * #include <aul_service.h>
1482  *
1483  * void set_camera_service_defapp()
1484  * {
1485  *      aul_set_defapp_for_service(TAKE_PICTURE_SVC,"com.samsung.camera");
1486  * }
1487  *
1488  * @endcode
1489  * @remark
1490  *      None
1491  *
1492  */
1493 int aul_set_defapp_for_service(const char *svcname, const char *defapp);
1494
1495 /**
1496  * @par Description:
1497  *      This API get the application appid associated with given service name
1498  * @par Purpose:
1499  *      This API use to get default application associteted with service name
1500  *      In general, Setting Application need this API.
1501  * @par Typical use case:
1502  *      Setting Application show mapping of default application/ service
1503  *
1504  * @param[in]   svcname         service string like "create_contact"
1505  * @param[out]  defapp          default application
1506  * @param[in]   len             length of defapp
1507  * @return      0 if success, negative value if fail
1508  * @retval      AUL_R_OK        - success
1509  * @retval      AUL_R_EINVAL    - invalid argument(content)
1510  * @retval      AUL_R_ERROR     - general error
1511  *
1512  * @pre
1513  *      None
1514  * @post
1515  *      None
1516  * @see
1517  *      aul_set_defapp_for_service
1518  * @code
1519  * #include <aul.h>
1520  * #include <aul_service.h>
1521  *
1522  * void get_camera_service_defapp()
1523  * {
1524  *      char appname[255];
1525  *      aul_get_defapp_for_service(TAKE_PICTURE_SVC,appname,sizeof(appname));
1526  * }
1527  *
1528  * @endcode
1529  * @remark
1530  *      None
1531  *
1532  */
1533 int aul_get_defapp_for_service(const char *svcname, char *defapp, int len);
1534
1535 /**
1536  * @par Description:
1537  *      This API sets callback fuction that will be called when applications die.
1538  * @par Purpose:
1539  *      This API's purpose is to listen the application dead event.
1540  *      In general, task manager Application need this API.
1541  *
1542  * @param[in]   func            callback function
1543  * @param[in]   data            user data
1544  * @return      0 if success, negative value if fail
1545  * @retval      AUL_R_OK        - success
1546  * @retval      AUL_R_ERROR     - general error
1547  *
1548  * @pre
1549  *      None
1550  * @post
1551  *      None
1552  * @see
1553  *      aul_listen_app_launch_signal
1554  * @code
1555  * #include <aul.h>
1556  *
1557  * int app_dead_handler(int pid, void *data)
1558  * {
1559  *      printf("===> %s : %d\n", __FUNCTION__, pid);
1560  *      return 0;
1561  * }
1562  *
1563  * void dead_listen()
1564  * {
1565  *      aul_listen_app_dead_signal(app_dead_handler, NULL);
1566  * }
1567  *
1568  * @endcode
1569  * @remark
1570  *      None
1571  *
1572  */
1573 int aul_listen_app_dead_signal(int (*func) (int, void *), void *data);
1574
1575 /**
1576  * @par Description:
1577  *      This API sets callback fuction that will be called when applications are launched.
1578  * @par Purpose:
1579  *      This API's purpose is to listen the application launching event.
1580  *      In general, task manager Application need this API.
1581  *
1582  * @param[in]   func            callback function
1583  * @param[in]   data            user data
1584  * @return      0 if success, negative value if fail
1585  * @retval      AUL_R_OK        - success
1586  * @retval      AUL_R_ERROR     - general error
1587  *
1588  * @pre
1589  *      None
1590  * @post
1591  *      None
1592  * @see
1593  *      aul_listen_app_dead_signal
1594  * @code
1595  * #include <aul.h>
1596  *
1597  * int app_launch_handler(int pid, void *data)
1598  * {
1599  *      printf("===> %s : %d\n", __FUNCTION__, pid);
1600  *      return 0;
1601  * }
1602  *
1603  * void dead_listen()
1604  * {
1605  *      aul_listen_app_launch_signal(app_launch_handler, NULL);
1606  * }
1607  *
1608  * @endcode
1609  * @remark
1610  *      None
1611  *
1612  */
1613 int aul_listen_app_launch_signal(int (*func) (int, void *), void *data);
1614
1615
1616 const char *aul_get_app_external_root_path(void);
1617 const char *aul_get_app_root_path(void);
1618 const char *aul_get_app_data_path(void);
1619 const char *aul_get_app_cache_path(void);
1620 const char *aul_get_app_resource_path(void);
1621 const char *aul_get_app_shared_data_path(void);
1622 const char *aul_get_app_shared_resource_path(void);
1623 const char *aul_get_app_shared_trusted_path(void);
1624 const char *aul_get_app_external_data_path(void);
1625 const char *aul_get_app_external_cache_path(void);
1626 const char *aul_get_app_external_shared_data_path(void);
1627 const char *aul_get_app_specific_path(void);
1628 const char *aul_get_app_external_specific_path(void);
1629 int aul_get_app_shared_data_path_by_appid(const char *app_id, char **path);
1630 int aul_get_app_shared_resource_path_by_appid(const char *app_id, char **path);
1631 int aul_get_app_shared_trusted_path_by_appid(const char *app_id, char **path);
1632 int aul_get_app_external_shared_data_path_by_appid(const char *app_id, char **path);
1633 int aul_get_app_usr_shared_data_path_by_appid(const char *app_id, char **path, uid_t uid);
1634 int aul_get_app_usr_shared_resource_path_by_appid(const char *app_id, char **path, uid_t uid);
1635 int aul_get_app_usr_shared_trusted_path_by_appid(const char *app_id, char **path, uid_t uid);
1636 int aul_get_app_usr_external_shared_data_path_by_appid(const char *app_id, char **path, uid_t uid);
1637
1638
1639 typedef int (*subapp_fn)(void *data);
1640
1641 int aul_set_subapp(subapp_fn cb, void *data);
1642 int aul_subapp_terminate_request_pid(int pid);
1643 int aul_is_subapp(void);
1644
1645 typedef int (*data_control_provider_handler_fn) (bundle *b, int request_id, void *data);
1646 int aul_set_data_control_provider_cb(data_control_provider_handler_fn handler);
1647 int aul_unset_data_control_provider_cb(void);
1648
1649 /** @} */
1650
1651
1652
1653 #ifdef __cplusplus
1654         }
1655 #endif
1656
1657
1658 #endif          /* __AUL_H__ */
1659
1660 /* vi: set ts=8 sts=8 sw=8: */