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